Animal Shards — Exploration and Alchemy assessment and proposed transition plan

Metadata

Type

project readme

Source ID

176f5557-a539-4826-89f1-02d03412d481

Created

2026-10-19T00:22:18.756981Z

Created by

Codex, requested by Túlio Caraciolo

Status

confirmed

Content URI

https://github.com/zeemaine/DoraJam/blob/master/README.md

External ID

animal-shards:DoraJam:README.md

Revision

2026-10-18-planning-uncommitted

Parser

—

Extractor

—

Content

# Animal Shards

Animal Shards is transitioning from an idle shard-merging rescue game into a touch-first exploration, gathering, alchemy, and animal-rescue adventure. Helena explores a magical forest, gathers ingredients, crafts potions, and heals animals to open new places to explore.

**Status — 2026-10-18:** assessment and proposed transition plan only. The playable code still implements the merge/stamina/diary baseline. No pivot gameplay has been implemented or playtested. This README supersedes the earlier report/diary roadmap; [Magic Diary design](docs/magic-diary-design.md) remains a historical design reference. [Local persistence](docs/local-persistence.md) describes the existing storage implementation.

**Primary reference: World of Warcraft**, specifically the exploration → Herbalism → Alchemy progression described in the pivot brief. The reference thesis is that discovering useful resources, improving professions, and applying crafted items to visible rescue needs can motivate further exploration. Fishdom Expeditions remains a secondary reference for direct world-object selection and automatic approach. This ordering follows the current user decision, superseding the pasted brief's original ordering. Multiplayer, combat, MMORPG inventory depth, and WoW's full economy are outside scope.

**Target:** browser-first/Poki, portrait-first touch interaction, landscape and desktop support, short sessions, minimal teaching friction. First rescue within 30–45 seconds is a proposed pacing target, not a measured result.

## Current project assessment

Repository facts below come from source, serialized scenes/prefabs, registries, and asset inspection. They establish what is present, not runtime correctness or build readiness.

| Area | Confirmed baseline and evidence | Transition recommendation |
|---|---|---|
| Engine/rendering | Unity **6000.4.10f1**, URP 17.4.0, Cinemachine 3.1.3, Input System 1.19.0; `ProjectSettings/ProjectVersion.txt`, `Packages/manifest.json`, `Assets/URP_Renderer.asset`. 2D sprites, physics and tilemaps. | Preserve versions and rendering setup. |
| Bootstrap | `GameManager.Start` initializes services, then registered controllers. `ControllerManager` instantiates prefabs, calls every `Initialize`, then every `PostInitialize`. Channels and scene anchors provide communication/placement. | Keep this architecture. Resolve cross-controller dependencies after initialization. |
| Scenes | Build settings enable `Assets/Scenes/gameplay.unity` and `diary.unity`. `leveledit` and `OBJTest` are also present. Gameplay registry instantiates `Assets/maps/Level01.prefab`; `Level02.prefab` exists. | Author a dedicated exploration scene and registry during implementation, keeping the baseline available for comparison. No general mode-switching framework needed. |
| Current loop | Auto-walk → timed inventory shard spawning → manual merge → contact-based automatic healing → stamina exhaustion or all-rescued ending → report → diary → next run. `InventorySpawner` is the actual resource source; the former README's ground-gathering description was not evidence of a world gathering system. | Replace the active loop; do not retain merging just because it is implemented. |
| Movement | `PlayerCharWalkBehavior` sets `Rigidbody2D.linearVelocity` in four directions, turns on named `RoadBlock` collisions, reverses after encounters, and boosts speed on pointer release. | Reuse body/animations; replace movement rules with destination approach. No existing arbitrary-destination pathfinding was established. |
| Input | `Assets/mmcore/Script/MouseHandler.cs` uses shared `MergeBoard/Select` and `MergeBoard/Move` actions. Existing boost and merge consumers are designed around that loop. | Keep Input System; introduce one owner for world tap/drag interpretation. Disable old input consumers in the new scene. |
| Camera/UI | `ContextCameraController` assigns Cinemachine follow targets and activates a curing camera. Gameplay uses uGUI/TMP, EventSystem, and a 768×1366 reference canvas. `DiaryResponsiveCameraController` has portrait/landscape framing. | Reuse components and UI art; add bounded pan/follow behavior. Diary framing is a useful example, not an exploration-camera implementation. |
| Animals/healing | `AnimalEntity` composes `Health`, `Sickness`, animator and cure effects. `PlayerCureBehavior` couples healing to shard stats, taps, stamina, and collision. `EncounterBehavior` rolls animals/sickness and supports respawning. No combat/enemy loop was found in the inspected gameplay scripts. | Keep animal presentation; replace automatic healing with explicit potion consumption and a short rescue animation. Author stable rescue identities. |
| Animal roster | Active `AnimalCatalog.asset` contains eagle, elephant, giraffe, lion and ostrich. A zebra definition/diary assets exist, but zebra is absent from that gameplay catalog. | Start with existing working animals; do not treat zebra as fully wired gameplay content. |
| Reports/meta | `ReportController`, `RescueTracker`, `DiaryRunCommitController`, diary scene/controllers/store, and `PlayerProgressStats` already implement reports, run-end rescue commits, gifts and saved stat application. They are not future work as the old README stated. | Preserve baseline and artwork; defer diary gift progression in the pivot to avoid a third economy competing with professions. |
| Persistence | Registered `LocalPersistence` provides `ISaveDocumentStore`. `AnimalShardsSaveEnvelope` schema 1 stores animal totals and chosen gifts, with primary/backup recovery. | Extend through an explicit migration; new resources/world state cannot be represented by current diary totals alone. |
| Portal/analytics | `WebSDKController.prefab` uses `WebPortalSDK`; SDK, JS bridge and Poki template are present. WebGL defines `MMCORE_POKI_ENABLED`. `PokiUnitySDK` exposes `customEvent` and `measure`; no pivot funnel is implemented. | Reuse bridge and verify delivery during browser QA; package/API presence does not establish analytics collection. |

### Migration dependencies that must be handled together

- `PlayerCharacterController` initializes walk, cure and orbit behaviors directly. Replacing only the movement component would leave old dependencies active.
- `WebPortalSDK` starts gameplay on the first **merge drag**, then responds to level events. `EncountersManager` raises loaded/unloaded events around encounters. The pivot needs a session lifecycle independent of both merging and individual rescues, otherwise playtime can be missing or fragmented.
- `RunController`, report, `LevelExplorerUIController`, tutorial, cure UI and diary run-commit wiring assume finite stamina runs. Remove these from the new active registry/scene together; leave their baseline implementation intact initially.
- `DiaryRunCommitController` saves at run end. A persistent exploration game must commit each gather/craft/rescue/unlock transaction, rather than waiting for a run that no longer ends.
- Existing save deserialization rejects schema versions other than 1. Merely increasing the version constant would make old saves fail validation. Migration must be explicit and retain existing diary data.

## Reusable assets and content gaps

| Assets | Assessment |
|---|---|
| `Assets/Art/character`, `Assets/Prefabs/GameplayHelena.prefab` | Character, directional walk animation and presentation can be reused; remove old behavior coupling in a new exploration prefab. |
| `Assets/Art/animals`, `Assets/Prefabs/animal.prefab` | Existing animal animations, icons and cure presentation support the rescue fantasy. Reuse a small subset first. |
| `Assets/Art/scenario/forest`, `forest_tilemap.png`, forest tile assets and `forest.prefab` | Forest trees, ground, mushrooms, flowers and vegetation exist. The inspected tile sheet includes varied plants and tree colors. Enough material for a prototype of small clearings; harvestable silhouettes and touch readability still need visual testing. |
| `Assets/Art/scenario/savana`, `Assets/maps/Level01.prefab` | Ground, rocks, bushes and trees remain useful. Existing map is structured around roads and directional blockers, not an authored exploration progression map. Recompose terrain; do not preserve its route constraints. |
| `Assets/Art/2D Casual UI`, `mergeui`, `diary`, report/diary prefabs | Reuse panels, icons, typography, animal photos and feedback presentation. Replace the merge grid with a small ingredient/potion display and contextual card. |
| `Assets/JMO Assets/Cartoon FX` | Existing pickup, light and magic effects are candidates for gathering and rescue; choose a few restrained effects and profile them. |
| Herbs/potions/station | Plants can become gatherable nodes. No dedicated herb/recipe/potion gameplay definitions or cauldron system were found. Exact potion/cauldron artwork was not established by inspection. Use simple labeled recipe/potion UI for the slice; a station is optional. |
| Audio | `AudioManager` exists, but no `.wav`, `.ogg`, `.mp3` or `.aiff` assets were found under Assets. Sound is a content gap, not a reason to delay the functional slice. |

Source art is approximately 27 MB on disk. This is **not** the WebGL download size or GPU-memory cost. Existing build folders do not establish performance of a future pivot build.

## Proposed game design

**Explore → discover → gather → craft → rescue → unlock → explore.** The player's decisions concern destinations, recipes and rescue priorities. Movement presents those decisions and should take only a small part of the session.

Recommended first version:

- Tapping a visible point of interest immediately reveals its requirements and selects it. An accessible target can initiate approach; a blocked target explains the gate without moving Helena into it.
- A gather tap requests approach plus collection once in range. Avoid making every herb require a second confirmation. Crafting and healing have explicit actions because they spend resources.
- Show the potion an animal needs, the ingredients still missing, and where known ingredients can be found. Do not hide discovery behind a recipe menu.
- Craft through a compact contextual panel available near the selected rescue. Keep crafting and healing separate, visible steps. Start without mandatory cauldron travel; add a station only if it creates a useful destination rather than repeated commuting.
- Healing consumes one matching potion, plays the existing rescue presentation and records the rescue once. No stamina run timer, shard DPS, tap spam, combat, or automatic healing on contact in the pivot slice.
- Herbalism XP comes from successful collection; Alchemy XP comes from successful crafting. Start with short authored thresholds: a new herb tier and a new recipe. Avoid a third reputation meter and profession skill trees.
- Rescue milestones open routes. Let players preview what lies beyond a gate. Keep profession prerequisites achievable with resources already reachable; never require an ingredient from behind the gate it opens.
- Keep two visible useful goals once the first rescue teaches the loop. Recipe ingredients and route choices should provide agency; more confirmations and longer walks do not create depth.

### Small world, meaningful discoveries

Recommend one scene containing three connected clearings, with authored approach anchors and a few explicit route connections. The forest assets support this composition, but the current road map is not ready to use unchanged.

| Clearing | Proposed content and purpose |
|---|---|
| 1 | Two easily distinguished common herbs, one recipe and one rescue. Show the next clearing's landmark. Complete the loop before adding progression screens. |
| 2 | Two rescue targets with different ingredient needs; introduce a second recipe and let the player choose an order. A visible milestone opens the next route. |
| 3 | Introduce one higher-tier herb and a final rescue using it. Demonstrate profession progression and a satisfying endpoint; do not promise unbuilt areas. |

First implement **one clearing**, then expand only if the loop is clear and pleasant. A two-clearing build can test comprehension, but three small clearings are the recommended Player Fit scope to observe discovery and progression beyond onboarding. Scope proposal: three herb types, two recipes, four authored rescues, one level-up in each profession, two route unlocks. Counts are hypotheses, not approved production requirements.

Common herbs should replenish at fixed authored nodes. Start with enough resources for the opening rescue without waiting. During expansion, use short in-session cooldowns only where needed for repeatability; no offline accumulation, random regional spawn pools or generalized spawning framework. Rare/progression discoveries and rescue IDs remain persistent and do not reset with herb replenishment. Test that spending ingredients in either available order cannot strand the player.

## Technical approach and risks

| Concern | Smallest viable approach and verification |
|---|---|
| Tap vs. camera drag vs. UI | One pointer gesture owner; press/release distance distinguishes tap from pan, UI captures its own pointers, secondary touches do not issue extra orders. Select world colliders only on a completed tap. Check touch, mouse, drag-release and focus loss. |
| Navigation | Obstacle-free interiors with authored interaction anchors; connect clearings through a tiny waypoint graph. Four-direction segments fit current animation. No grid/A*, NavMesh baking or package change unless authored geometry proves insufficient. New taps replace the pending destination; revalidate target access and requirements at arrival. |
| Distant/unreachable POIs | Preview requirements immediately. Route only through unlocked connections; show the blocking condition if no route exists. Keep distances short and avoid queuing unwanted actions. Never teleport through gates. |
| Camera | Keep an orthographic Cinemachine camera. Pan a bounded target, suspend follow while inspecting, resume on destination selection or an explicit recenter control. Prevent follow from fighting the user's drag. Frame the selected POI above contextual UI. |
| Responsive presentation | Reuse uGUI/TMP. Portrait gets a compact bottom context card; landscape can reposition it without hiding the target. Test narrow phones, landscape, desktop and resizing; existing canvas settings do not prove these layouts work. |
| Data/components | Small ScriptableObject definitions for ingredients/recipes/requirements; scene POIs with stable IDs and approach anchors. Add a movement behavior, POI interaction controller, resource/crafting state owner and contextual view as needed. Use existing controller/service conventions; avoid a general quest or ability system. |
| World progression | Explicit rescue-ID milestones and clearing gates; reveal authored content on unlock. No streaming, procedural world generation or fog simulation required for three clearings. |
| Save correctness | Extend the versioned envelope with inventory counts, profession XP, rescued POI IDs, unlocked clearing IDs and any necessary harvested-node state. One domain transaction validates costs, mutates state, and saves once before awarding presentation/events. Repeated taps/reloads cannot duplicate XP, potion consumption or rescues. |
| Save compatibility | Migrate schema 1 explicitly, preserving diary fields. Start new exploration progress separately; do not convert old rescue totals into completed new-world rescues. Use one save owner or explicit reload/merge discipline so the old DiaryStore cannot overwrite newer fields from a stale snapshot. |
| Mobile/WebGL cost | Keep all three clearings small, use static decorations and modest effects, avoid per-frame searches across the world. Measure a real build's compressed transfer, loading, texture memory and frame pacing on phone/Chromebook before deciding on optimization. Do not equate package inventory with build bloat. |
| Portal lifecycle | First accepted world interaction replaces merge-drag activation; loading-finished stays once per app load. Define active exploration, explicit pause and suspension transitions; crafting/rescue actions must not accidentally end the session. Verify actual browser callbacks before submission. |

## Incremental implementation plan — proposed, not started

### Phase 1 — One complete rescue

**Objective:** prove the new interaction and emotional loop together, not a navigation demo.

- **Reuse:** bootstrap/services/channels, Helena and one animal, forest ground/vegetation, UI panels, cure feedback, local document storage and SDK bridge.
- **Change/add:** separate exploration scene/registry and character prefab; destination movement, gesture handling, small contextual UI, two ingredients, one recipe, one potion-funded rescue. Adapt portal start trigger and add the new save section/migration alongside the first durable actions.
- **Dependencies:** settle the crafting/stamina/diary defaults below; author short unobstructed routes and stable object IDs. Inspect registry and prefab dependencies as a group when disabling legacy systems.
- **Risks:** input conflicts, old controllers continuing to run, duplicated resource transactions, navigation waiting, schema migration losing existing data.
- **Acceptance:** on touch and mouse, select → approach → gather → craft → heal works without merge/tap-boost behavior; first rescue target is 30–45 seconds; UI clicks and pans never collect accidentally; changing target cancels the pending action; save/reload preserves resources and rescue exactly once; blocked paths explain why they are blocked. User verifies feel and runtime presentation.
- **Exclude:** additional clearings, XP progression, mandatory station, respawn economy, diary gifts and new art production beyond essential legibility.

### Phase 2 — Choice, discovery and professions

**Objective:** determine whether the player wants to perform a second and third loop.

- **Reuse:** Phase 1 interactions/state/presentation and existing forest/animal variants.
- **Change/add:** three connected clearings, three herb types, two recipes, four rescues, fixed-node replenishment, two profession XP tracks, one level-up per track and two milestone gates. Add compact progression feedback and new recipe/herb previews.
- **Dependency:** Phase 1 loop and save transactions work; no progression gate depends on inaccessible resources.
- **Risks:** repetitive errands, mandatory waiting, recipe deadlocks, insufficient reason to explore, progression UI clutter.
- **Acceptance:** after the first rescue there are two understandable useful goals; either rescue order remains completable; a new herb and recipe are visibly unlocked; clearing/rescue progression survives reload while common herbs replenish according to the chosen policy; reaching the final clearing produces a clear payoff.
- **Exclude:** rare-item RNG, generalized spawn pools, third reputation system, skill trees, sanctuary, combat and large-world authoring.

### Phase 3 — Player Fit readiness

**Objective:** produce a measurable browser test of comprehension and voluntary continuation.

- **Reuse:** existing Poki SDK/template and all Phase 2 content; no new analytics framework.
- **Change/add:** first-occurrence funnel events, targeted onboarding cues only where observation shows confusion, responsive polish, save recovery checks and measured performance fixes.
- **Dependency:** human testing of the complete content path and a human-produced WebGL build.
- **Risks:** missing/duplicate SDK events, fragmented gameplay time, poor touch targets, slow cold load, saves masking the first-session experience.
- **Acceptance:** test fresh and returning saves on phone, desktop and Chromebook where available; verify lifecycle callbacks and milestone delivery; record exact build identifier, loading/frame observations and funnel results; confirm no legacy run-ending/report screen or ad mechanic interrupts the pivot. Submit only after these checks.
- **Exclude:** monetization, broad optimization without measurements, new SDKs and production-scale content.

## Player Fit validation

Primary question: **Can touch-first exploration, Herbalism and Alchemy make animal rescue understandable quickly and motivate players to continue into a new area?** This is an unvalidated design hypothesis; no test evidence for the pivot exists yet.

Track first POI selected, first herb collected, first potion crafted, first animal healed, second animal healed, second/third clearing entered, and first level gained for each profession. Distinguish recipe unlocks from actual use. Include elapsed active time, build identifier and fresh/returning-session context where the existing transport supports them. Deduplicate first-occurrence milestones within a session; emit completion events after successful state commits, not button presses.

Use the existing `customEvent`/`measure` bridge only after checking which events the testing dashboard actually exposes. If custom funnel delivery is unavailable, use local debug traces plus observed playtests and portal aggregate metrics; do not label local logs as collected Player Fit analytics.

Assess time to first rescue, step-to-step conversion, second-rescue continuation and clearing reach. The 30–45-second opening target is a hypothesis. No numeric retention pass threshold is established; choose it with the actual test setup/baseline. Observe whether players choose another useful goal without prompting, and whether travel, missing ingredients, controls or recipe comprehension explain exits.

## Open decisions before implementation

Only these materially change the first slice; recommended defaults are documented so planning can proceed:

1. **Crafting location:** contextual crafting near a rescue (recommended) versus mandatory cauldron travel. A cauldron adds a destination, art and travel/pacing requirements.
2. **Legacy progression:** remove stamina runs and diary gifts from the pivot's active loop (recommended). Preserve saves/assets; consider animal photos as simple rescue rewards later. Keeping gifts now requires redesigning their shard/stamina effects and balancing a third progression system.
3. **World identity:** use the existing forest with existing savanna animals for a magical prototype (recommended), versus requiring a new biome-consistent roster before testing. The latter materially increases art scope.

The broader exploration/Herbalism/Alchemy direction and WoW as primary reference are current goals. The implementation details, scope counts and defaults above remain proposals pending review.

## Run, testing and persistence cheat sheet

- Open this `DoraJam` Unity project using **6000.4.10f1**. Current build scenes are `gameplay` then `diary`; no exploration-pivot scene exists yet.
- Current loop: merge equal-level shards; taps boost walking/healing; exhaustion/all-rescued opens report; diary contains persistent bond progression. Tuning assets are under `Assets/Data`; the baseline reference below is retained for orientation, not pivot balancing.
- Use [local-persistence.md](docs/local-persistence.md) for service ownership and flush behavior. Save key: `animal_shards.save`; previous revision: `animal_shards.save.backup`.
- To test a fresh **web** save, clear site data for the exact test origin in browser developer tools and reload. This clears other data on that origin too. In editor/debug tooling, remove both document keys through the persistence service and flush; leave runtime systems free of direct PlayerPrefs access.
- This assessment checked source/asset references, registry wiring, configuration, art and Git diffs. No Unity launch, compilation, playable build, device profiling or gameplay verification was performed. No focused project test suite was found in the inspected Assets tree.
- Next checkpoint: review this plan, then make a documentation checkpoint before beginning the first complete-rescue slice. Existing uncommitted settings/generated-file changes belong to the user and are outside this assessment.

## Legacy tuning reference

The following tables are retained from the previous README for the still-existing merge/stamina baseline. Values are historical documentation, not freshly validated tuning or targets for the pivot; inspect the serialized asset before changing it. The prior full roadmap remains available in Git history and the historical Magic Diary design document.

### Player — `Assets/Data/PlayerCharacterTuning.asset` (`PlayerCharacterDefinition`)

| Field | Current | What it does |
|---|---:|---|
| `characterBaseSpeed` | 0.7 | Base auto-walk speed (units/sec). |
| `maxCharacterSpeed` | 2 | Hard cap on walk speed (base + tap boost combined). Effective top speed Helena can reach. |
| `walkTapSpeedIncrease` | 0.05 | Speed added to the walk tap-boost per click/tap. |
| `autoSpeedDecreaseSize` | 0.05 | Speed removed from the walk tap-boost on each decay step. |
| `autoSpeedDecreaseInterval` | 0.5 | Seconds between walk tap-boost decay steps. |
| `cureTapBoostStep` | 0.1 | Cure speed added per tap (and removed per decay step), as a fraction of base cure speed. |
| `cureTapBoostDecayInterval` | 0.5 | Seconds between cure tap-boost decay steps. |
| `cureMaxTapBoost` | 0.6 | Max cure tap-boost. `0.6` = up to +60% cure speed when fully boosted. |
| `maxStamina` | 100 | Stamina each run starts with, and the bar's full value. |
| `drainPerSecond` | 3.25 | Base stamina drained per second while actively healing. |
| `severityDrainMultiplier` | 0.5 | Extra drain proportional to severity. `0` = severity ignored; `1` = severity-1.0 animal drains 2× base. At 0.5, a severity-1.0 animal drains 1.5× base. |
| `efficiencyMultiplier` | 1 | Upgrade hook: divides drain so future efficiency upgrades cost less stamina. `1` = no change. |
| `drainEnabled` | true | Master switch for stamina drain. Turn off for testing (infinite stamina). |

**Drain formula:** `drainPerSecond × (1 + severity × severityDrainMultiplier) / efficiencyMultiplier` per second.

### Shards — `Assets/Data/ShardsDefinition.asset` (`ShardsDefinition`)

`curingSpeedPerLevel` (array index = shard level):

| Level | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| Curing speed | 1 | 2 | 4 | 9 | 20 | 45 | 100 | 220 |

Cure rate = **sum** of every equipped shard's curing speed, then `× (1 + cureTapBoost) × sickness.regenModifier`. Empty slots are ignored; levels beyond the table clamp to the last entry (220). The steep curve makes merging strongly preferable to hoarding low shards.

Spawning is also tuned here (driven via `InventorySpawner`, which reads these values):

| Field | Current | What it does |
|---|---:|---|
| `baseSpawnTime` | 0.8 | Seconds before the first shard spawn. |
| `spawnTimeIncrement` | 0.4 | Added to the interval per shard already spawned, so spawning slows over the run (`baseSpawnTime + numSpawns × increment`). |
| `spawnLevelWeights` | `[100, 0, 0, 0, 0, 0, 0, 0]` | Relative chance of spawning each level. Currently 100% level 0 — all higher shards come from merging. |

`GetRandomSpawnLevel(bigShardBonus)` rolls a level from those weights; the upgrade-driven `bigShardBonus` (0 = base distribution) scales each weight by `(1 + bigShardBonus × level)` to bias toward bigger shards. `bigShardBonus` is set via `InventorySpawner.SetBigShardBonus(...)` — the hook for a future "better shard chance" upgrade.

### Animals — `Assets/Data/animals/*.asset` (`AnimalDefinition`), catalog `AnimalCatalog.asset`

| Animal | `animatorId` | `maxHealth` |
|---|---:|---:|
| eagle | 0 | 120 |
| ostrich | 1 | 150 |
| elephant | 2 | 240 |
| giraffe | 3 | 210 |
| lion | 4 | 180 |

`maxHealth` is the full life pool. `animatorId` feeds the animator's `animal` integer parameter to select the sprite. Each encounter picks a random animal from the catalog.

### Sickness — `Assets/Data/sickness/*.asset` (`SicknessDefinition`), catalog `SicknessCatalog.asset`

Catalog order (top → bottom) is the **tier** referenced by severity bands. The asset's own `id` field is unrelated to tier.

| Tier | Asset | Display name | `severity` | `regenModifier` |
|---:|---|---|---:|---:|
| 0 | `scabies` | Sun-Bleached Scabies | 0.10 | 1.0 |
| 1 | `bloat` | Acacia Bloat | 0.15 | 1.0 |
| 2 | `wheeze` | Dust-Lung Wheeze | 0.20 | 0.9 |
| 3 | `necrosis` | Thorn-Flash Necrosis | 0.30 | 0.9 |
| 4 | `delirium` | Heatstroke Delirium | 0.40 | 0.8 |
| 5 | `blindness` | Viper-Spit Blindness | 0.50 | 0.8 |
| 6 | `rot` | Scavenger's Rot | 0.55 | 0.7 |
| 7 | `fever` | Fossil-Bone Fever | 0.60 | 0.6 |

- `severity` — fraction of the animal's `maxHealth` removed at spawn, **and** the input to the stamina-drain scaling.
- `regenModifier` — multiplies cure speed while this sickness is active (`1` = no effect). Higher tiers now also heal slower (down to `0.6` on fever), so the worst sicknesses are punishing on both starting health and cure rate.

### Sickness ramp — `Assets/Data/sickness/SicknessProgression.asset` (`SicknessProgressionConfig`)

Maps an encounter's order index to a severity band (the tier range it may roll). First matching rule wins; `default` applies when none match.

| Encounter index | Min tier | Max tier |
|---|---:|---:|
| 0–3 | 2 | 3 |
| 4–6 | 3 | 4 |
| 7–10 | 4 | 6 |
| 11–18 | 6 | 7 |
| default | 1 | 3 |

Sickness ramps from mid tiers (wheeze/necrosis) toward the worst (rot/fever) as Helena explores deeper into the level. Bands are clamped to the catalog's real tier range (0–7).

### Per-prefab / per-component tuning (not ScriptableObjects)

These are inspector fields on prefabs, listed here so they're discoverable when balancing:

| Component | Field(s) | Purpose |
|---|---|---|
| `InventorySpawner` | — | Spawn timing and level weights now come from `ShardsDefinition` (`baseSpawnTime` / `spawnTimeIncrement` / `spawnLevelWeights`); the spawner just reads them and drives the timer bar. |
| `InventoryManager` | `numOfColumns` = 6 | Merge-grid width / slot count. |
| `EncounterBehavior` | `spawnTime`, `overrideSeverityBand`, `overrideBand` | Average respawn delay after a despawn (randomized ±10%; `-1` = no respawn) and optional per-encounter severity-band override. |
| `OrbitingShardsBehavior` | `maxVisuals` 12, `radius` 1, `verticalSquash` 0.6, `rotationSpeedDegrees` 90, `bobAmplitude` 0.1, `centerLerpSpeed` 8, `depthSortingRange` 2 | Visual-only orbit ring around Helena that lerps to the animal during a cure. (Script defaults — a prefab may override.) |
| `ComboBehavior` | `curesToLevelUp` | Combo-bar pacing. Note: combo-driven spawning is currently disabled in code. |

Metadata JSON

{
  "baseline_commit": "58d6f5e",
  "implementation_started": false,
  "local_path": "/Users/tulio/Projects/animal-shards/DoraJam/README.md",
  "status": "local uncommitted documentation; remote URL identifies repository location, not published revision"
}