godot-genre-survival

NEVER Do (Expert Anti-Patterns)

Physiology & Needs

• NEVER use constant "Needs" decay; strictly scale with activity (e.g., Sprinting drains hunger 3x faster than idling).
• NEVER use Instant Death for starvation/dehydration; strictly trigger gradual HP drain and provide distinct visual/audio warnings.
• NEVER use float timers for exact life-critical checks; strictly use is_equal_approx() or <= to prevent 0.0 precision misses.
• NEVER represent world time/day cycles within UI scripts; strictly use an AutoLoad (Singleton) to decouple state from visuals.

Gathering & Inventory

• NEVER make gathering tedious without progression; strictly implement Tiered Tool Scaling (e.g., Stone Axe = 1 wood/hit, Steel Axe = 5 wood/hit) to reward technical advancement.
• NEVER allow infinite inventory stacking; strictly use Weight Capacity or strict Stack Limits (e.g., 64 items) to force strategic resource management.
• NEVER force players to "Guess" crafting recipes; strictly use a Discovery System where recipes unlock upon acquiring materials.
• NEVER forget to duplicate(true) a shared Resource (like Item Durability); otherwise, all instances will break simultaneously.
• NEVER store heavy item/crafting definitions in Node properties; strictly use custom Resource containers for lightweight data.

World & Performance

• NEVER spawn threats at Respawn Points; strictly enforce a Safe Zone radius (Beds/Spawn) where enemy spawning is prohibited.
• NEVER instance 10,000 individual MeshInstance3D nodes for foliage; strictly use MultiMeshInstance3D for batched draw calls.
• NEVER load massive world chunks synchronously; strictly use ResourceLoader.load_threaded_request() to prevent hitches.
• NEVER save complex dictionaries to standard text files; strictly use binary serialization for speed and size efficiency.
• NEVER run procedural terrain/noise algorithms on the main thread; strictly offload to the WorkerThreadPool.
• NEVER hardcode massive crafting tables in GDScript; strictly use ConfigFile or JSON for easy balancing and modding.

---

Expert Components (scripts/)

> MANDATORY: Prefer these scripts over inline stubs. Do not paste pass architectures into scenes.

[survival_patterns.gd](scripts/survival_patterns.gd)

MANDATORY first read — Activity-scaled vitals, MultiMesh populate, threaded chunk load, WorkerThreadPool noise chunks (generate_noise_chunk_async), GridMap snap/place, Persist collect, deep duplicate(true).

[status_depletion_manager.gd](scripts/status_depletion_manager.gd)

MANDATORY for needs — Activity-scaled hunger/thirst in _physics_process (aligns with NEVER: no constant decay).

[inventory_data.gd](scripts/inventory_data.gd)

Core Resource-based grid inventory: stack limits, metadata, add/remove.

[inventory_slot_data.gd](scripts/inventory_slot_data.gd)

Lightweight UI↔logic slot DTO.

[inventory_slot_resource.gd](scripts/inventory_slot_resource.gd)

Serializable slot Resource with durability tracking.

[modular_inventory_controller.gd](scripts/modular_inventory_controller.gd)

Controller wiring inventory data to UI signals.

[interactable.gd](scripts/interactable.gd)

Universal harvest / pickup / world-trigger interface.

[crafting_recipe_processor.gd](scripts/crafting_recipe_processor.gd)

Ingredient check → consume → grant result (discovery-friendly).

---

Decision Tree — Survival Systems

| Need | Route |

|------|-------|

| Item / recipe / durability data | Custom Resource + [inventory_slot_resource.gd](scripts/inventory_slot_resource.gd) |

| Bag / stack / weight | [inventory_data.gd](scripts/inventory_data.gd) + [modular_inventory_controller.gd](scripts/modular_inventory_controller.gd) — weight caps / drag-drop UI → godot-inventory-system (Do NOT re-teach grid UI here) |

| Hunger / thirst | [status_depletion_manager.gd](scripts/status_depletion_manager.gd) — set sprinting from movement |

| Harvest / open / pickup | [interactable.gd](scripts/interactable.gd) |

| Craft | [crafting_recipe_processor.gd](scripts/crafting_recipe_processor.gd) |

| Base build snap | [survival_patterns.gd](scripts/survival_patterns.gd) place_if_empty / GridMap |

| Forest foliage | MultiMesh via populate_nature — never 10k MeshInstance3D |

| Chunk stream | load_world_chunk threaded path in survival_patterns |

| Procedural noise / biomes at scale | generate_noise_chunk_async in survival_patterns — or MANDATORY godot-procedural-generation when terrain exceeds chunk helpers |

| Phase | Peer skills | Purpose |

|-------|-------------|---------|

| 1. Data | godot-resource-data-patterns | Item/recipe Resources |

| 2. UI | godot-ui-containers, godot-inventory-system | Grid + drag/drop |

| 3. World | godot-procedural-generation, godot-3d-world-building | Noise, GridMap |

| 4. Logic | godot-signal-architecture, godot-state-machine-advanced | Needs + interaction |

| 5. Save | godot-save-load-systems | World + inventory + recipes |

Key Mechanics (pointers, not tutorials)

Needs (activity-scaled)

Wire movement → StatusDepletionManager.sprinting. Empty vitals → gradual HP drain + warnings (never instant death). See script — do not reintroduce constant decay_rate in _process.

Tiered Tool Scaling

Stone Axe 1 yield / Steel Axe 5 yield / proximity Auto-Saw — encode as item Resource metadata, not hardcoded harvest scripts.

Spawn Safe Zones

Re-roll spawn points outside bed/player_beds radius before enabling threat spawners.

Godot-Specific Tips

• TileMapLayer (Godot 4) for 2D worlds — do not use Godot 3 TileMap APIs.
• FastNoiseLite for biome/resource density (off main thread via WorkerThreadPool for heavy maps).
• ResourceSaver / binary serialization for large inventories and chunk dicts.
• Y-Sort for top-down 2D occlusion with trees/props.

Common Pitfalls

1. Tedium — Scale gather yield with tool tier.
2. Inventory clutter — Generous stacks + storage sinks.
3. No goals — Tech tree / boss pressure beyond pure survive.

---

Elite Technical Implementations

> MANDATORY when starting base-building snap or biome/noise work: read [elite-technical-patterns.md](references/elite-technical-patterns.md). Do NOT Load for first-pass needs/inventory/crafting — use the script catalog above.

Deep recipes (on demand)

| Topic | Reference / script |

|-------|-------------------|

| Needs / crafting / tools | [key-mechanics.md](references/key-mechanics.md) + bundled survival scripts |

| Base build grid snap | [elite-technical-patterns.md](references/elite-technical-patterns.md) + [base_builder.gd](scripts/base_builder.gd) |

| Biome / spawn safety | [elite-technical-patterns.md](references/elite-technical-patterns.md) + [biome_generator.gd](scripts/biome_generator.gd) |

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Resources — Item definitions, recipe tables, and inventory slots belong as Resources so designers retune weight, stack limits, and durability without code changes.
• Idle and physics processing — Hunger/thirst decay must multiply by delta in _physics_process (or _process) so vital drain stays frame-rate independent.
• Singletons (Autoload) — World time, day/night, and global needs state belong in Autoloads so UI scripts never own the clock.
• Using signals — Inventory and crafting should emit change signals so HUD grids update without polling every frame.
• Saving games — Persist inventory, unlocked recipes, base GridMap cells, and player vitals across sessions.
• Binary serialization API — Large world/chunk dictionaries should use binary packs instead of bulky text dumps.
• Background loading — Stream world chunks with ResourceLoader.load_threaded_request() to avoid hitching while exploring.
• Using GridMaps — Base-building snaps and octant-batched structure pieces use GridMap.local_to_map / set_cell_item.
• Using MultiMesh — Forests, rocks, and harvestable foliage must batch via MultiMesh instead of thousands of MeshInstance3D nodes.
• Using multiple threads — Procedural noise/terrain generation belongs on WorkerThreadPool, never the main thread.
• FastNoiseLite — Biome and resource density maps sample FastNoiseLite gradients for organic world layout.
• AStarGrid2D — When players place structures, mark cells solid so AI reroutes around new bases immediately.

Related Skills

Prerequisites

• godot-gdscript-mastery — is_equal_approx, Resource duplicate(true), and delta-scaled timers are foundational before vital and inventory logic.
• godot-resource-data-patterns — Items, recipes, and slot payloads must be Resource-first so durability and stack metadata serialize cleanly.
• godot-signal-architecture — Inventory/crafting buses should signal UI and interaction systems without tight Node coupling.
• godot-autoload-architecture — Day cycles and global needs managers that survive scene swaps follow Autoload ownership rules.

Complements

• godot-inventory-system — Grid stacking, weight capacity, and drag/drop UIs deepen the survival bag beyond genre sketches.
• godot-save-load-systems — Versioned world saves cover inventory Resources, base cells, and unlocked recipe lists.
• godot-procedural-generation — Noise biomes and resource scatter compose with FastNoiseLite patterns in this skill.
• godot-3d-world-building — GridMap tooling, collision, and LOD practices support large player-built bases.
• godot-ai-navigation — Threat AI that respects built walls needs NavigationAgent / AStar updates when structures change.
• godot-ui-containers — Crafting menus and inventory grids are Control layout problems, not gameplay scripts.
• godot-game-loop-harvest — Tiered tool yield and gather loops share harvest-loop patterns with survival gathering.

Downstream / consumers

• godot-monte-carlo-balancer — After recipe costs, tool tiers, and need decay rates are data-driven, Monte Carlo careers prove hours-to-tech and starvation risk bands before shipping balance sheets.
• godot-genre-open-world — Open-world survival consumes chunk streaming, safe-zone spawn, and scarcity loops defined here.
• godot-economy-system — Trading posts and crafted-good sinks extend survival crafting into soft-currency economies.

Master

• godot-master — Library router and mirrored module entry; use when discovering peer skills or syncing shared script mirrors after Domain Skill edits.