Novo Rio – Agroforestry Simulation RPG

Novo Rio is a browser-based agroforestry simulation RPG developed as part of EKO – Residência Artística, a cultural residency funded by FAC – Fundo de Apoio à Cultura do Distrito Federal, Secretaria de Cultura e Economia Criativa / GDF. The game is built around the principles of sintropic agriculture — the Brazilian regenerative farming philosophy associated with Ernst Götsch. Players manage degraded terrain in a Rio de Janeiro setting, restoring it by planting real Brazilian species (Feijão Guandu, Banana, Cajuzinho, Ipê-roxo, Milho, Abacaxi), managing soil health parameters, and adapting to a realistic climate system with drought, heavy rain, heat waves, and seasonal multipliers. The backend runs a real-time tick engine (APScheduler, 6-hour cycle) that drives plant growth, applies climate events, and evaluates soil health. EKO, powered by a local Ollama LLM with Redis-backed conversation history, acts as the player's AI farming advisor.

Sintropic agroforestry is a proven regenerative land-restoration technique with limited public awareness and no gamified entry point. Most environmental games either abstract away the technical complexity of real agriculture or focus on punishment mechanics. Novo Rio aims to teach real planting logic — actual species tolerances, soil parameter interdependencies, seasonal growth multipliers — through gameplay, making the learning curve invisible.

Build a simulation game that: (1) models real Brazilian agroforestry species and soil dynamics accurately; (2) runs a real-time tick engine with configurable time compression for testing; (3) integrates a local LLM as an in-game guide with game-state awareness; (4) supports WhatsApp as a first-class input channel so players can interact without opening a browser.

• ◈Solo developer — game design, backend, frontend, data modeling, AI integration

1. 01APScheduler tick engine with TIME_SCALE_FACTOR — a 6-hour real-time scheduler drives all game state changes. The TIME_SCALE_FACTOR environment variable compresses game time (e.g., TIME_SCALE_FACTOR=24 makes 1 real hour = 1 game day), making the full plant lifecycle testable in hours rather than months.
2. 02YAML-driven species configuration with hot-reload — species.yml defines all plant parameters (germination days, maturity days, drought tolerance, harvest yield). The tick_day() function re-reads the YAML on every cycle so game designers can tweak species balance without restarting the server.
3. 03Weighted soil health index — a custom scoring algorithm computes a 0–100 soil health score across 6 parameters with per-parameter ideal ranges and severity thresholds. This produces meaningful quality categories (Excelente / Muito Bom / Regular / Crítico) that give players actionable feedback rather than raw numbers.
4. 0415% neighbor quadrant propagation — applying water, fertilizer, or compost to one quadrant propagates 15% of the effect to the 4 adjacent quadrants (N/S/E/W), modeling real soil moisture diffusion and making spatial planting decisions consequential.
5. 05Plant lifecycle state machine — 5 states (SEMENTE / MUDINHA / MADURA / COLHIVEL / COLHIDA / MORTA) with time-driven transitions controlled by species parameters. Drought tolerance determines how many tick cycles a plant survives without water before dying.
6. 06WhatsApp as a primary input channel — a /whatsapp/message endpoint parses natural-language text commands ('plantar 3 regador') and maps them to game actions, rate-limited by the same 6-hour cycle system as the web UI. The game was designed so a player could fully manage their farm from WhatsApp.
7. 07Dual sync/async API architecture — both src/api/ (sync with run_in_threadpool) and src/api_async/ (native async) coexist, reflecting a migration in progress toward full async FastAPI. The coexistence allowed incremental migration without breaking existing endpoints.
8. 08EKO/Ollama with Redis conversation context — the /eko endpoint proxies messages to a local Ollama instance with per-session conversation history stored in Redis, enabling EKO to give contextual planting advice that references prior exchanges.
9. 09Secret tool abilities scaffolded in tools.yml — each tool has a secret_special_ability field defining a discovery mechanic ('if used for ACTION in CLIMATE with SPECIES → unlock bonus'). Not yet implemented in the game engine but fully specified in the data layer, designed to add a hidden discovery layer for experienced players.

• →APScheduler combined with TIME_SCALE_FACTOR is a powerful testing pattern for time-driven games — being able to run a full crop cycle in minutes rather than months makes iterating on game balance tractable without requiring a separate test harness.
• →YAML for game data configuration (species, tools, inputs) separates content authoring from code changes in a meaningful way — a non-programmer game designer can tune species balance without touching Python files, which matters as the game expands.
• →Modeling real ecological systems (soil pH, organic matter interdependencies, drought tolerance) produces more engaging simulation mechanics than invented parameters, because the real relationships are already interesting and non-obvious to most players.
• →WhatsApp as a game input channel is architecturally straightforward (a webhook endpoint + NLP command parsing) but produces a fundamentally different game experience — asynchronous, low-friction interactions that fit naturally into daily routines rather than requiring dedicated play sessions.
• →Dual sync/async API coexistence in FastAPI is manageable but creates maintenance overhead — having two parallel implementations of the same endpoints means any bug fix must be applied twice. A cleaner migration path would be to add an async wrapper layer rather than maintaining two code trees.

Functional prototype — active development paused, resuming planned