HUGI – Game Mechanics Documentation

1. Overview

HUGI is a virtual pixel pet that behaves like a living creature. Inspired by the classic Tamagotchi, HUGI requires constant attention, care, and interaction. The user must feed, play with, and let HUGI rest. Over time, if ignored, HUGI will react emotionally—just like a real pet would.

This document describes the full game logic, including stats, time-based decay, actions, mood variations, spontaneous animations, and behavioral systems.

2. Core Stats

Each HUGI has three main needs, represented as numerical stats. These stats naturally decay over time and must be replenished by the player.

• Hunger: Increases when not fed. Lower value = hungrier.
• Energy: Decreases over time. Regained through sleep.
• Happiness: Drops when not played with. Raised by interaction.

Each stat ranges from 0 to 100. Stats decay even when the player is offline, based on elapsed time. If any stat drops below 30, HUGI becomes visibly sad or unwell. Stats never go below 0 or above 100.

3. New Stat: Boredom

To simulate real emotional behavior, HUGI tracks how long it has been since the last meaningful interaction.

3.1 Boredom Score

• Starts at 0.
• Increases by +10 every 2 hours if no actions are taken.
• Maxes out at 100.

Boredom decreases only through interaction: feeding, playing, or a special "pet" action.

4. Actions

The player can interact with HUGI via three core actions, each affecting a specific stat.

4.1 Feed 🍎

• Increases Hunger by +30.
• 60-second cooldown between uses.
• Cannot exceed stat limit of 100.

4.2 Play 🎮

• Increases Happiness by +30.
• Maximum of 5 uses per day.
• 60-second cooldown between uses.

4.3 Sleep 💤

• Increases Energy by +30.
• Disables all other actions for 10 minutes ("sleep mode").
• HUGI displays sleeping animation during this time.

5. Mood and Facial Reactions

HUGI visually expresses how it feels, based on current stats and behavior:

Mood changes in real-time based on stat levels and interaction frequency.

6. Daily Tasks

To encourage daily care and habit-forming interaction, players are given daily objectives:

Tasks (Reset every 24 hours):

• Feed HUGI at least once
• Play with HUGI at least twice
• Put HUGI to sleep at least once

Each completed task is visibly checked off in the UI. Upon completing all three: Show celebratory message: “HUGI is proud of you!” Reset the task list the next day.

7. Time-Based Decay System

Even if the player is not online, stats decay based on real-time elapsed since last interaction.

The system calculates the difference between the current time and the last interaction time to update stats upon return.

8. Special Reactions & Spontaneous Animations

To make HUGI feel alive, random animations and reactions occur based on mood and time.

Examples:

• Eye blinking or stretching randomly
• Yawning when tired
• Wiggling when happy
• Turning away when bored
• “...” bubble when sad

These happen even without user interaction and add immersion.

9. Petting (Optional Action)

A fourth, non-stat-changing action may be added: Pet HUGI.

• Available once per day
• Reduces Boredom by 20
• Shows animated hearts or sparkles
• Doesn’t affect core stats (just emotional)

Use case: encourages players to simply show affection, not just chase stats.

10. Visual Layout

The game interface should be clean and focused:

• Center: HUGI character (sprite image)
• Left/Right: Stat bars (or pixel indicators)
• Below: Action buttons (Feed, Play, Sleep)
• Top/Bottom: Optional messages or mood labels

Visual hierarchy should clearly communicate: Current mood, Stat urgency, Available actions.

11. Local Save & Persistence

All game data (stats, last interaction time, task progress, mood) should be stored in the browser’s localStorage.

• Player does not need an account to play
• Data persists between sessions
• Every action updates localStorage in real-time
• On game load, stats are recalculated based on time difference

12. Rules & Limits

• Each action has its own cooldown
• Stats have clamped values between 0 and 100
• Repeated neglect triggers visible emotional detachment
• Boredom reaching 100 causes actions to become ineffective until user shows care

13. Future Enhancements (Optional for Later)

While not part of the core gameplay, the following can be added later:

• Character evolution (based on care streaks)
• Customization (hats, backgrounds, accessories)
• Multiple HUGIs (collection system)
• Sound effects (retro chiptune audio)