docs: add design document

docs/design/toonpets-design.md

@@ -0,0 +1,236 @@
+# Video Game Concept
+*Working Title: Toon Pets*
+
+## Abstract
+
+I am developing a video game. The game will be primarily intended to be played on smartphone devices, such as iPhone and Android. I will be developing the video game using a game engine called Godot 4. I will develop the game using native code for Android or iPhone, such as Kotlin or Swift, where necessary.
+
+## Video Game Overview
+
+In the video game, players will have a virtual pet. Each player begins with a pet that appears identical to the pet that all other players begin the game with. The virtual pet will be able to evolve. The virtual pet will be able to eat different types of food. The different types of food include meat, fruit, and sweets. The food is given to the virtual pet by the player.
+
+## Inspiration
+
+The video game is heavily inspired by four different video games and franchises:
+
+- **Bomberman 64: The Second Attack!** features a character named Pommy as the sidekick and playable character for player two. Pommy is a "mimic" that can evolve. The video game for this project borrows heavily from the evolution mechanic seen for Pommy.
+
+- **Toon Town Online** was a massively multiplayer online role playing game. Players were able to work together to fight enemies in turn based combat using a variety of weapon types called "gags". Some weapon types worked well in conjunction with others, while some had the opposite effect. The interaction of weapon types forced players to coordinate strategically.
+
+- **Pocket Pikachu** was a standalone handheld digital pet that also functioned as a pedometer. Every 20 steps earned 1 watt, which could be used for activities that positively affected the relationship with Pikachu. As the relationship became more positive, Pikachu would display a wider range of animations and more positive emotions.
+
+- **Megaman Battle Network** features characters who own a PET (personal terminal), which hosts their own singular artificial intelligence warrior called a NetNavi. The NetNavi stays primarily in the PET but can leave to visit the Net and interact with other characters' spaces. This inspires the pet visitation and co-habitation systems.
+
+## Core Design Pillars
+
+The game leans toward a relationship-building idle game experience. The design pillars, in order of priority:
+
+1. **Relationship Building** — Daily engagement through care routines and meaningful interactions with the pet
+2. **Multiplayer Capability** — Social features that create tangible connections between players and their pets
+3. **Diegetic Interactivity** — Commands given to the virtual pet will be diegetic instead of traditional button presses
+
+## Guiding Philosophy: Wabi-Sabi
+
+In traditional Japanese aesthetics, wabi-sabi centers on the acceptance of transience and imperfection. It is often described as the appreciation of beauty that is "imperfect, impermanent, and incomplete." This philosophy serves as a guiding principle for Toon Pets.
+
+### Where Wabi-Sabi Manifests
+
+**Imperfection as story.** The pet's personality emerges from how it's been cared for — not from optimization. A pet that evolved down a "suboptimal" path isn't worse; it's *yours*, shaped by your choices and attention. The imperfections are the story.
+
+**Lived-in spaces.** The sphere reflects the pet's journey. Items brought back from visits carry history. The space isn't a showroom — it's a home with character.
+
+**Graceful limitation.** The partnership model accepts that the player doesn't have total control. The pet offers what they offer, and the player works with it. There's grace in that limitation.
+
+**Transience as meaning.** Visits end. Co-habitation is temporary. The moments two pets share are fleeting, which is precisely what makes them worth having. This counters the "permanent collection" mentality of most games.
+
+**Incompleteness by design.** No player accesses all 6 weapon types. No evolution path unlocks everything. The game assumes the player will not have it all, and that this is okay — even beautiful.
+
+### Visual and Design Implications
+
+- Slightly weathered textures over sterile polish
+- Asymmetry over rigid symmetry
+- Environments that feel grown rather than constructed
+- Animation that has weight and idiosyncrasy rather than mechanical perfection
+
+## The Sphere
+
+The game takes place inside a spherical enclosure — the pet's private world contained within the player's smartphone. The phone isn't just a terminal; it's the enclosure itself. The player looks through a window into the pet's home.
+
+### Environment Design
+
+The game features side-scrolling movement within a closed loop. If the pet walks in one direction, they arrive back at their original starting point. This is diegetically justified by the spherical space — the pet is walking around the interior surface of a sphere.
+
+This design serves multiple purposes: it constrains development scope, creates a cozy and intimate feeling space, and encourages players to engage with each other rather than explore an endless world alone.
+
+The sphere's appearance changes based on the pet's evolution. Each evolution path produces a distinct visual environment, giving players aesthetic reasons to pursue specific evolutions.
+
+### The Pet as Intelligent Companion
+
+The pet is not a possession — it is an intelligent species and a companion. The sphere belongs to them, and the player is a guest they've chosen to let in. This framing draws from Pommy in Bomberman 64: The Second Attack, who was a sentient partner rather than a creature to be owned.
+
+This distinction affects how systems feel. When the pet leaves to visit another pet's sphere, they are entering someone else's home as a social act. When a friend's pet visits, two intelligent beings are sharing an intimate space. The host pet's personality affects how that visit feels.
+
+### Customization Through Partnership
+
+Players will likely want to customize the sphere's interior. However, since the sphere is the pet's private world, the pet should have autonomy over their own space. The solution is a partnership model where player and pet are equals.
+
+The pet curates what customization options are available based on their evolution and personality:
+
+- A bold, combat-hardened pet might present trophies or training equipment
+- A gentle, well-fed pet might offer cozy nesting materials or plants
+- Items brought back from visits to other spheres become customization options with stories attached
+
+The player picks from what the pet brings forward, but the pet sets the menu. This achieves several goals:
+
+- **Natural scope limitation:** No universal furniture catalog needed — each evolution path unlocks different aesthetic possibilities
+- **Earned customization:** Items feel earned rather than purchased because the pet found, made, or brought them back
+- **Relationship reinforcement:** A pet with shallow bond offers few choices; a pet who trusts deeply offers more, or offers to change things they previously seemed attached to
+
+The pet allows the player to have a voice in their world. The player and pet are partners.
+
+## Evolving
+
+The virtual pet will evolve into different evolutions depending on what food the virtual pet eats. The virtual pet will evolve in a series of stages, up to three times. Each evolution forms a decision tree that spans outward, resulting in 17 permutations.
+
+At level 3 in the decision tree, the virtual pet can evolve by eating enough sweets. The resulting evolution would depend on whether the virtual pet first evolved by eating meats or fruits, resulting in two additional permutations.
+
+If the player is dissatisfied with what the virtual pet evolves into, it will be possible to revert the evolution with the use of a particular item.
+
+### Full List of Evolutions
+
+**Level 1:**
+- evolution_1
+
+**Level 2:**
+- evolution_1 (fruit) → evolution_2
+- evolution_1 (meat) → evolution_3
+
+**Level 3:**
+- evolution_1 (fruit) → evolution_2 (fruit) → evolution_4
+- evolution_1 (fruit) → evolution_2 (meat) → evolution_5
+- evolution_1 (meat) → evolution_3 (fruit) → evolution_6
+- evolution_1 (meat) → evolution_3 (meat) → evolution_7
+
+**Level 4:**
+- evolution_4 (fruit) → evolution_8
+- evolution_4 (meat) → evolution_9
+- evolution_5 (fruit) → evolution_10
+- evolution_5 (meat) → evolution_11
+- evolution_6 (fruit) → evolution_12
+- evolution_6 (meat) → evolution_13
+- evolution_7 (fruit) → evolution_14
+- evolution_7 (meat) → evolution_15
+
+**Sweet Evolutions (Level 3 only):**
+- evolution_4 or evolution_5 (sweet) → evolution_16
+- evolution_6 or evolution_7 (sweet) → evolution_17
+
+## Obtaining Food
+
+Food is necessary for the virtual pet to evolve. Food can be obtained through two methods:
+
+### Passive Food Generation
+
+Basic food is generated passively, covering the pet's fundamental needs without requiring combat. Possible approaches include:
+
+- **Time-based:** Food appears in a bowl every X hours, player taps to feed
+- **Activity-based:** Pedometer-style system where steps or shakes generate currency that converts to food (most aligned with Pocket Pikachu's spirit)
+- **Pet-initiated:** The pet "forages" on its own and player approves or interacts with what it found
+
+### Combat (Optional)
+
+Combat accelerates evolution and provides access to rare resources. Combat rewards include:
+
+- **Rare food types** that guarantee specific evolution paths
+- **Sweets exclusively from combat** — since sweets unlock the secret level 3 evolutions, this makes those forms a multiplayer achievement
+- **Cosmetic rewards** — accessories, backgrounds, or animations
+- **Relationship boost multipliers** — combat together strengthens the bond faster
+
+## Combat
+
+The virtual pet will fight enemies in turn based combat. Combat is optional but provides advantages for players who engage with it. Combat is largely multiplayer focused, though it will be possible to fight enemies solo.
+
+Turn-based combat was chosen for ease of development, wireless latency tolerance, and the ability of players to coordinate attacks with each other.
+
+The game features a diegetic approach while remaining turn based. A hypothetical example: pressing and holding down on the virtual pet to initiate a windup. The windup allows the player to cancel if they realize the move will not work with the strategy other players are preparing.
+
+Players choose which attack to command the virtual pet to execute. Each attack is of a specific weapon type. There are 6 different weapon types.
+
+### Evolving to Unlock Weapon Types
+
+When the player first begins and the virtual pet has not evolved, the virtual pet will only know one attack of one weapon type. As the virtual pet becomes more experienced, it may unlock more attacks of that weapon type. However, the virtual pet will only unlock a new weapon type by evolving.
+
+The virtual pet can evolve three times, unlocking one new weapon type each time. The maximum number of weapon types a virtual pet can utilize is 4. Each weapon type has 7 possible attacks, each more powerful than the last. Because one player cannot utilize all 6 attack types, they are incentivized to work together with other players.
+
+### Encountering Enemies
+
+There is no overworld for the virtual pet to travel. Enemies will randomly appear. The likelihood of an enemy appearing increases if the player shakes their device, taps on their screen, interacts with their virtual pet, or walks.
+
+## Relationship System
+
+When the player gives food to the virtual pet or battles with the virtual pet, the relationship positively increases. The "relationship" is a tangible metric, but it will not be shown to the player directly. Instead, the relationship manifests through visible behavior changes.
+
+### Behavior Driven by Relationship
+
+As the relationship improves, the virtual pet displays increasingly rich behaviors:
+
+- **Early relationship:** Pet responds when you interact
+- **Mid relationship:** Pet anticipates your patterns (perks up when you usually open the app)
+- **Deep relationship:** Pet initiates play, shows off, brings you things
+
+### Personality Emergence
+
+The pet's disposition develops based on how the player has treated it. A pet that's been fed consistently might become trusting and affectionate. One that's been through lots of combat might become bold or protective. Personality is not fixed at evolution but emerges from care patterns.
+
+## Social Systems
+
+### Multiplayer Connection
+
+Players automatically connect to each other given that they have the game open and are in the same immediate vicinity (a radius of 10 to 20 feet, or the same room). Multiplayer capabilities on one smartphone will not be possible; each player needs their own device.
+
+### Intentional Social Connection
+
+Beyond proximity-based connection, the game features intentional social layers:
+
+- **Opt-in visibility:** Your pet is only "seen" by others if you choose to be social that session
+- **Friend linking:** A deliberate pairing ritual (pets sniff each other, both players confirm) that persists across sessions
+- **Strangers vs friends distinction:** Combat with strangers is transactional, but linked friends' pets remember each other and develop their own relationship over time
+
+## Pet Visitation System
+
+Inspired by Megaman Battle Network, where NetNavis can leave their PET to visit the Net and other characters' spaces. In Toon Pets, the phone serves as the sphere, and the pet can visit linked friends' spheres through established bonds. Pets travel between spheres to visit each other.
+
+### Visiting Mechanics
+
+- You "send" your pet to a friend's sphere (or it asks to go)
+- While away, your pet is literally absent from your screen — you feel the emptiness
+- The pet returns after some time with a story: what it did, how the other pet reacted, maybe something it brought back
+
+### What Happens During Visits
+
+- Pets play together, share food, train together
+- Visits generate relationship boosts for both pets toward each other
+- Rare outcome: pets could find or create something together that neither could alone (evolution catalyst, cosmetic, shared animation)
+
+### Temporary Co-habitation
+
+A friend's pet can stay in your sphere temporarily. You see two pets interacting on your screen — playing, napping together, showing off for each other. This makes social connection feel tangible rather than abstract.
+
+*Design questions to resolve:*
+
+- Initiating co-habitation: Does the visiting pet's owner "send" it, or does your pet "invite" it?
+- Duration: Fixed time window, open-ended until recall, or does the guest pet get "homesick"?
+- The empty sphere: When your pet is visiting elsewhere, what do you see? (The emptiness may become emotionally meaningful — you're looking into an empty home)
+- Interactions: Can you feed the guest pet? Can the guest's owner see what's happening?
+- Combat: Can two co-located pets fight together as a team?
+
+## Open Design Questions
+
+- Enemy design and variety
+- The 6 weapon types and their interactions
+- Visual and audio direction
+- Target audience and age rating
+- Which passive food generation method to use
+- Whether all 17 evolutions are accessible to solo players, or if some are gated behind multiplayer
+- Monetization approach
+- Is the "outside" of the sphere ever visible or relevant, or is it purely abstract?