Celadora (Godot 4.3) - v0.1 Vertical Slice

Celadora is an open-source sci-fi fantasy RPG prototype built in Godot 4.3. This release is a playable single-player vertical slice designed with service seams for future MMO networking.

Requirements

• Godot Engine 4.3 (stable)
• Desktop platform (tested design target: keyboard + mouse)

Run Locally

1. Open Godot 4.3.
2. Import project from:
   • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/project.godot
3. Click Run Project (F5).

Build / Export

1. In Godot, open Project > Export.
2. Add your target preset (Windows/macOS/Linux).
3. Export using default settings (no external binary dependency required for v0.1).

Controls

• W/A/S/D: Move
• Shift: Run
• Space: Jump
• Mouse: Look
• Left Click: Swing equipped first-person tool (mine/attack resolves on impact window)
• E: Interact (terminals and interactables)
• I: Toggle Inventory
• O: Toggle Objective Checklist
• C: Toggle Crafting
• J: Toggle Lore Journal
• M: Toggle Marketplace
• F5: Manual save
• F8: Skip day/night phase (dev/test convenience)
• F9: Reset local progress (save + inventory + lore + market state)
• F3: Toggle debug overlay (FPS/position/biome/objective/dream status)
• Esc: Toggle mouse capture

HUD notes:

• Top row: compass and marker bearings
• Bottom row 1: dynamic route guidance for the next incomplete objective
• Bottom row 2: current objective progression
• Bottom row 3: world status (day/night, biome, Dream Keeper window, next lore marker direction/distance)
• Bottom row 4: contextual interaction hint (mine/attack/interact target)
• Center status line: current target integrity/HP
• First-person viewmodel: arms, hands, and active tool are visible; crafted Moonblade (Prototype) auto-equips visually
• Completion debrief panel appears automatically when all v0.1 objectives are done, with run summary stats
• Bottom row 5: system controls (inventory/crafting/lore/market/interact/save/reset)
• Bottom row 6: movement controls
• Hit feedback: lightweight red flash when taking damage

Gameplay Loop in v0.1

• Spawn on Celadora with eight visible moons.
• First-person embodiment: visible arms/hands/tool with motion sway, bob, fatigue shake, and hit kick.
• Mine dust fragments and energy crystals.
• Moon dust identity loop:
  • each dust type now matches its moon color exactly,
  • each moon dust has a unique particle geometry,
  • each moon dust has distinct gravity/bounce/drag in-world behavior when dropped.
• Glow spectrum:
  • dust glow is data-driven per type (0.0 no glow -> 1.0 fully luminous).
• Rarity power curve:
  • rarer dust tiers include extra “exotic” stat hooks (for example critical_chance, gravity_resistance, jump_boost).
• Fight Greegion Miner Bots.
• Craft Celadora Alloy and Moonblade (Prototype).
• Unlock lore entries at Enok's Kingdom Ridge, Makuna's Shore, and Greegion Ruins.
• Encounter rare Dream Keepers at night for Dream Seed drops.
• Prime the locked Greegion Ruins terminal after meeting requirements (Moonblade + Dream Seed + lore unlocks).
• Use local marketplace listings with Celador Credits.

Objective reliability notes:

• Starter resource cache now spawns near the initial area (multiple dust types + energy crystals).
• Starter fast-path was tuned further: denser starter cache and tighter spawn radius for early crafting momentum.
• Dream Keeper now guarantees at least one night encounter after a short delay if you still need a Dream Seed.
• Lore markers now use taller pulsing beacons and switch to completion tint once unlocked.
• Ruins terminal now exposes clear missing-requirements messaging and a primed future-boss hook state.
• Marketplace includes Quick Sell Bot Scrap for faster early-economy flow.
• Event log service records key gameplay actions for future server-authoritative migration.
• Objectives are now latched and persisted via world_state flags so completed milestones stay complete.
• Save service now uses schema migration (schema_version) and normalizes legacy saves into current objective/world-state flags.
• Lore marker beacons now highlight the nearest unfinished marker to reinforce route clarity.

Data-Driven Balancing

All game data is editable JSON under /data and loaded at runtime. Runtime validation enforces required Celadora IDs, moon count/type coverage, and core recipe/enemy/location contracts. First-person viewmodel tuning is also JSON-driven via /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/data/viewmodel.json.

Add a New Dust Type or Item

1. Add a new object in /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/data/items.json.
2. Provide fields:
   • id, name, category, tags, stackable, max_stack, base_value, description, modifier
3. If it is dust, include "dust" in tags to make crafting rules discover it.
4. For moon dust, include a dust_profile object with:
   • moon_id, shape, gravity_scale, bounce, drag, glow_strength, rarity
5. Keep dust_profile.shape unique per moon dust type so each particle silhouette is distinct.
6. Set glow_strength in the 0.0 to 1.0 range to control emissive intensity.

Add a New Recipe

1. Add recipe object to /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/data/recipes.json.
2. Set ingredients, optional special, and outputs maps.
3. Crafting UI reads this file automatically on startup.

Add/Balance Enemies

• Edit /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/data/enemies.json.
• Tune HP, speed, aggro, damage, and drop values.

Expand World Size/Biomes

• Edit exported values in WorldSpawner node inside /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scenes/world/World.tscn:
  • world_radius_tiles
  • tile_size
  • height_scale
• Biome thresholds are in /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/world/world_spawner.gd.

Tune First-Person Arms/Tool Feel

1. Edit /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/data/viewmodel.json.
2. Tune:
   • base_transform: camera-relative position/rotation for arms/tool.
   • sway, bob, fatigue: movement feel and stamina feedback.
   • actions.mine and actions.attack: duration + impact timing windows.
   • tools.states: per-tool offsets/colors for miner and moonblade.
3. Re-run preview:
   • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/dev/quick_preview.sh 8060

Visual Realism Toolkit (Open Source)

• Integrated now (no external assets required):
  • Procedural terrain shader:
    • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/assets/shaders/terrain_biome.gdshader
  • Water shader:
    • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/assets/shaders/celadora_water.gdshader
  • Sky dome shader:
    • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/assets/shaders/celadora_skydome.gdshader
  • Runtime world visuals controller:
    • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/world/world_visuals.gd
• Recommended external OSS stack:
  • Material Maker (MIT)
  • Poly Haven (CC0)
  • ambientCG (CC0)
  • Sky3D (MIT, optional)
  • Godot SSR Water (MIT, optional)
  • godot_spatial_gardener (MIT, optional)
  • Basis Universal (Apache-2.0, optional texture compression)
• Detailed integration notes:
  • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/docs/realism_stack.md
• Renderer note:
  • Web preview currently uses compatibility renderer for reliability. Keep this for browser builds; evaluate a separate desktop Forward+ profile when adding heavier visual plugins.

Architecture Summary

• Autoload singleton: GameServices
• Modular services: inventory, crafting, save, lore, marketplace, network stub.
• Provider seam: NetworkService interface + LocalNetworkService implementation.
• Persistent world progression seam: GameServices.world_state (used by ruins-terminal state and future world flags).
• Economy isolation: disabled TokenBridge stubs in /scripts/economy.

Developer Shortcuts (DX)

• One-command validate+export+preview+open:
  • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/dev/quick_preview.sh 8060
• Export Web quickly:
  • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/dev/export_web.sh
• Start local Web preview:
  • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/dev/run_web_preview.sh 8060
• Stop local Web preview:
  • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/dev/stop_web_preview.sh
• Run smoke checks:
  • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/dev/smoke_check.sh
• Run automated QA agent (headless + report files):
  • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/qa/run_qa_agent.sh
  • Outputs:
    • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/docs/reports/qa_latest.md
    • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/docs/reports/qa_latest.json
    • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/docs/reports/qa_browser_objective_latest.json
    • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/docs/reports/qa_combined_latest.md
• Build combined QA snapshot report only:
  • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/qa/build_combined_report.sh
• Run browser objective-flow QA directly:
  • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/qa/run_browser_objective_qa.sh 8060
  • Notes:
    • Uses Playwright via local Node tooling (package.json).
    • Marks result inconclusive when headless browser lacks WebGL2 support.
    • Includes a first-person viewmodel visibility gate (arms/hands/tool projected in viewport).
• Run v0.1 goal audit report:
  • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/scripts/dev/goal_check.sh
  • Output:
    • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/docs/reports/goals_status_latest.md

AI Agent Workflow (AX)

• See:
  • /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/docs/agent_playbook.md
• It defines UX/DX/AX priorities, safe iteration checklist, and command sequence for future agent contributions.
• Balancing telemetry:
  • Debug overlay (F3) now includes spawn telemetry (resource/enemy/pickup counts + nearest distances), resource mix summary, and fast-path milestone timers.

Next Milestones

1. Dedicated server foundation
   • Move simulation authority for inventory/combat/economy to a backend process.
2. Nakama integration
   • Implement NetworkService methods against Nakama RPC/storage APIs.
   • Add session/auth bootstrap and matchmaking hooks.
3. MMO shard/instance strategy
   • Hybrid model: region shards + instanced high-load zones.
   • Cross-shard travel services and state handoff.
4. Authoritative economy + anti-cheat
   • Server-side validation for resource drops, trades, and crafting outputs.
   • Event audit logs, anomaly detection, anti-duplication protections.
5. Content roadmap
   • Eight-moon travel loop.
   • Moon Sword questline progression.
   • Dream Keepers narrative arc.
   • Shadow King threat arc and late-game dungeon activation.

License

MIT. See /Users/parisvega/Desktop/2 Business/Vega Ventures (100)/Celadora/LICENSE.