Technical direction

Rules separate from presentation, names instead of coordinates, and nothing gets in without a gate.

The 3D game is a single Godot 4.7.2 Standard project, in GDScript with the Forward+ renderer, opened at the root of its repository and working without any other checkout. GLB models and WAV audio use Git LFS; the versioned .import and .gd.uid parameters preserve resource identity. The game rules that came from the 2D live in scripts/compartilhado/ (inventory, stamina, health, talents, faith, cards, collection, recipes, works, sales, affinity, saving), without referencing a single 2D type; the valley's services in scripts/autoload/; the screens in scripts/ui/.

The migration from 2D to 3D, measured file by file on 09/29/2026, showed that almost everything carries over, because the 2D always kept rules in autoloads and drawing in scenes: of the 30 logic autoloads, 25 didn't reference a 2D type. What ties a rule to the 2D is almost never the type, it's the input (which key triggers it) — and that can be separated. The rule that governs everything: the 3D is not rewritten. Migrating means adding, never redoing what is already standing.

10 principles

What is not negotiable

One project, one engine, LFS for what's heavy

Godot 4.7.2 Standard, GDScript and Forward+ (with a Compatibility mode for GPUs that don't support the profile); the root project.godot registers the 40 autoloads and opens inicio.tscn. No engine migration and no engine upgrade mid-jam without proven need. GLB, legacy FBX and WAV in Git LFS; caches, builds, raw files and credentials stay out of Git; the game needs no keys to run.

Rules separate from presentation

What an action does carries across; which key triggers it and which screens block the key stay in each game's project. That's how the hand key left Inventario and moved to the input controller, and how the 2D screens (CanvasLayer and Control) draw over the 3D without knowing it's 3D. Player-facing text is born as data (JSON), never as a GDScript constant, because a constant doesn't translate.

The 3D is not rewritten

A 3D asset is never swapped for 2D art (a sprite doesn't replace a GLB; 2D art only goes into the interface, as an icon). A mechanic that already works in 3D remains the owner of its subject: the clock is Dia, the narrator is GuiaPedro, the HUD is prototype_hud, the map is mapa_jogo. Only what the 3D lacks is built from scratch. If a slice deletes, redoes or retires something that already runs, it's wrong and needs to be cut another way.

The name is the contract; the anchor is the implementation

The Lugares autoload translates a place name into a position — Vector2 in 2D, Vector3 in 3D — and the caller doesn't see the difference. A name the valley doesn't have yet returns NENHUM and nothing breaks: the quest opens without a compass, the system runs with the place absent, and on the day the region grows the name starts resolving without touching any quest. A type annotation is coupling just as real as a function call, and it doesn't show up in a search by name.

Nothing gets in without a gate

Each slice adds or adjusts a behavior test in tests/ and shows that it detects the defect (falsification). The runner tools/prototipo_3d/testar.ps1 runs the suite with an isolated profile per gate, a time ceiling and a check for compilation errors: compilation errors and hangs fail, and an exit code of zero alone doesn't demonstrate that the game opened. Only the PIDs the runner started may be killed. On 10/02/2026 the suite had 51 gates passing.

Declared debt, not forgotten debt

What is missing lives in lists with the reason written down: FALTAM_NO_VALE in Lugares (the lagoon), FALTAM_TRADUCAO in the language gate, the roof queue in the 2D, the Tripo pieces not yet exported in the catalog. The gate reads these lists to check that no entry is written wrong, and the system keeps running with the missing piece — the same choice as the asset catalog.

Performance measured on the reference computer, not estimated

A GeForce GTX 1660 Ti (Max-Q) is the reference. Measurements that changed decisions: uncompressed textures at 2.49 GB of VRAM → 0.74 GB with VRAM Compressed; the forest as one MultiMesh per species that never left the frame → blocks of 40 units with distance-based LOD (17.33 M → 5.65 M triangles in the far view); valley assembly from ~29 s to ~5 s by replacing the measurement of each point against every segment with cell grids, with a bit-for-bit identical result.

Data in res://, saves in user://, one source for the version

Data is read from res://data/ and the save uses user:// in its own MythsValleyPrototype3D directory, separate from the 2D. The save format is a Godot variant (it stores Vector3 naturally), with atomic writes and stepwise migration; a new public field goes into O_QUE_GUARDAR or FORA_DO_SAVE with the reason written down, and the gate checks both. The version and build are declared once, in data/historico_3d.json, and both the menu footer and the save stamp read from there.

Secrets out of the repository; generation only on request

Credentials live in local files read by tools/comum/chaves.ps1 and in the local Tripo profile; no key goes into the repository, the executable or the build. Art and audio generation consumes credits and only happens on explicit request, with each asset keeping its provenance and credits. For the planned LLM conversation, the provider's key stays as a secret in a service, never in the client, and a secret hidden in the game is not authentication.

Three reserves and one focused interaction

Stamina sustains effort, running and jumping; breath sustains swimming; health takes damage. E acts on one target at a time, ahead of the body; conversations and notices pause the clock. Build 9 reduced loading, shadows, woods and physics work, and the minimap now uses a static photograph.

9 rules

In practice, day to day

Before implementing, read the issue and the gate for the subject and check the current code: old issues may describe as missing something that has already been incorporated.
Each slice: implement, add or adjust the behavior check, show that it detects the defect, run the suite with an isolated profile, log it in CHANGELOG_3D and cite the issue in the commit body. New work goes in feature/<nome> and a PR to main.
Suite: .\tools\prototipo_3d\testar.ps1 (or -Teste salvamento). The suite runs headless; captures and tests that depend on the mouse (smoke_opening, mapa_fluxo, smoke_test) use the normal renderer.
git lfs pull before the first import: the preflight fails models or WAVs that are still LFS pointers.
Windows export via export_presets.cfg to build/windows/ (create the folder first), with templates from the same Godot version.
Keys in code, not in the Input Map: teclas_movimento.gd (WASD, arrows or both) and atalhos.gd (remappable letters with swap; W, A, S and D reserved), saved in user://controles.cfg.
A shared rule is a copy checked byte by byte by a gate; the list of forked files (catalogo, inventario, equipamento, mochila, as of 10/01/2026) awaits the author's decision before any synchronization.
Positions and visual decisions don't live as Vector3 inside world_builder: the generator reads the saved composition.
Debugging: JOGAR_3D.cmd -Lugar igreja starts at a place in the valley; -Compatibility switches the renderer; -Godot CAMINHO.exe points to another executable.

Where it shows up

The size of the code
Game scripts, tests and tools live in their own folders. File and line counts, autoloads, scenes, shaders and JSON data are measured in the Git snapshot recorded in the statistics; the project page shows current figures for code, tests and data.
The Salvamento that crossed over without adaptation
It looked like the most tangled, and it crossed over without a single line changed, because it uses get_node_or_null everywhere and degrades on its own where a system doesn't exist; only Versao had to be born locally, reading from historico_3d.json.
CadernoDoVale and CadeiaDeMissoes
The valley's own quest mechanism: one progress entry per quest and chains attached to villagers, reading their data files. Objectives include materials, delivery, conversation, events, counts, building projects, visits and offerings; test gates check the chain and the resources needed to complete it.
The minimap gate
The quest target pointed to whoever had just spoken, not to what the player pinned on the panel — and it lasted because the minimap had never had a gate. It has one now, with seven questions.
The menu flyover
Planned offline against the real triangles of the valley, recorded in data/sobrevoo_menu.json and checked frame by frame by tests/sobrevoo_livre.gd; if the anchors or the scale change, the menu warns and falls back to the old ellipse.

Where it comes from

The documents behind this area

The guidance above sums up these direction documents of the game.

Architecture — the game's scenes, autoloads and catalogs
Game vision — what the game is and what it brings together
Validation — how the project is checked after import
3D plan — the game's direction and next steps
Game overview — the Myths' Valley 3D summary
Development history — the steps before the standalone repository
3D prototype decisions — what was decided and when
The living valley — day and night, residents and the valley's sound
3D changelog — what changed in each build
Places — each place's name and where it is
Game version — the number stamped on each build
Keyboard shortcuts — the keys the player can remap

Other areas

Visual direction 3D art and the Tripo workflow World direction Sound direction Historical and narrative direction Project decisions

Next: Project decisions