Direction · 3 of 7
The KML provides the land; the author composes the valley on top of it, and the valley lives by the hour and by the tide.
The valley is a real place: Bom Jesus dos Pobres, a fishing village in Bahia's Recôncavo (Saubara, BA), on the Bay of All Saints. The geographic reference is a drawing the author made in Google Earth and exported as KML — 26 features: 12 points, 8 streets, 2 river lines, 3 areas (Farm, Square and Forest) and the Mapa polygon, which frames the camera. The data stays in real meters; for the demo, one Godot unit equals 4 m, with a vertical exaggeration of 2.0, so the valley is walkable without losing its relative geography.
By the September 29, 2026 decision, KML is an import source and geographic reference, not the permanent owner of every object. The territorial foundation (terrain, coast, rivers, streets, areas) can be regenerated; the authored composition (houses, named trees, posts, props, NPCs, interaction points, cameras) is editable in Godot and survives every reimport. Above this foundation the valley lives: astronomical sunlight for its latitude, 1887 lights switching on at dusk, a 2.4 m tide over nautical-chart bathymetry, woods singing day and night, and villagers with stations by period and fourteen new hourly routines.
World direction
The KML provides the land; the author composes the valley on top of it, and the valley lives by the hour and by the tide.
The valley is a real place: Bom Jesus dos Pobres, a fishing village in Bahia's Recôncavo (Saubara, BA), on the Bay of All Saints. The geographic reference is a drawing the author made in Google Earth and exported as KML — 26 features: 12 points, 8 streets, 2 river lines, 3 areas (Farm, Square and Forest) and the Mapa polygon, which frames the camera. The data stays in real meters; for the demo, one Godot unit equals 4 m, with a vertical exaggeration of 2.0, so the valley is walkable without losing its relative geography.
By the September 29, 2026 decision, KML is an import source and geographic reference, not the permanent owner of every object. The territorial foundation (terrain, coast, rivers, streets, areas) can be regenerated; the authored composition (houses, named trees, posts, props, NPCs, interaction points, cameras) is editable in Godot and survives every reimport. Above this foundation the valley lives: astronomical sunlight for its latitude, 1887 lights switching on at dusk, a 2.4 m tide over nautical-chart bathymetry, woods singing day and night, and villagers with stations by period and fourteen new hourly routines.
10 principles
What is not negotiable
Two sources of truth, kept apart
The imported geographic base (KML and derivatives: relief, coast, rivers, streets, boundaries and areas) and the authored composition (scenes and resources editable in Godot: houses, trees, lampposts, props, NPCs, interaction points and cameras). A KML reimport may update the base, but it may not delete, recreate over, or silently reposition the authored composition; conflicts are surfaced for human review. An object's absence from the KML does not authorize removing it from the game.
Real meters, playable scale
The KML stores WGS84 and the importer applies a local projection with its origin at the Square; the region catalog defines how many meters fit in one unit (scale_m_per_unit). Bom Jesus uses 1 unit = 4 m: the Farm and the Square are ~220 m apart instead of ~890 m. Street, river and shoreline widths have minimums in units so they stay playable at any factor (Rua Principal is 11 m, the lookout street 4.2 m, the others 5 m). Each future region will have its own WGS84 anchor; a single origin is not used for all of Brazil.
The world is the Mapa frame, in 16:9, on the mainland
The importer fits the drawn frame to exact 16:9 (3,614 × 2,033 m; the width grows, centered); terrain, coast, forest and boundaries end there. Beyond the frame, the nautical chart's land continues as distant relief: Bom Jesus is not an island. Invisible walls close the edge. The sea follows the bathymetry of DHN nautical chart 1108 (a grid of 550 × 500 cells of 10 m), with the water at spring-tide high tide and its color drawn from the real depth.
The valley lives by the hour
The Dia autoload keeps continuous time (0–24) and advances at the chosen speed (Stopped, Slow, Normal, Fast); the sun follows the astronomical position for latitude -12.8° in late September (rising in the east around 6 a.m., culminating to the north, setting in the west), the sky goes from midday blue to orange to deep blue, mist thickens before dawn and a faint moon comes up at nightfall. There was no electric light in 1887: oil lampposts on the three corners of the Square and in the chapel courtyard, kerosene lamps at doorways, a bonfire in the yard and candles in the windows light up when daylight drops below 45%, with flickering flames.
The tide and the sea are part of the place
The tide is set in AJUSTAR → Scenery: no tide, the site's cycle (semidiurnal, two lows and two highs per game day), a slow cycle, or fast for demonstration; real amplitude of 2.4 m. On the flood the water darkens (turbidity); at low tide the exposed bottom turns to mud with mirror-like pools, canoes run aground on their sides, the reef flats appear and footsteps turn to mud and puddle. You can wade into the sea, swim where the water is deeper than your chest, and a shark prowls the deep part — Pedro and the villagers are never targets.
Fill vegetation and authored vegetation
The woods use a fixed seed (1887) across woodland zones — 3,117 background trees, with landmark clearings — keeping clear of roads, rivers, beach, open areas and markers, in 40-unit blocks culled outside the camera with distance-based LOD. This vegetation can remain batched for performance. Authored vegetation — near paths, houses, landmarks and narrative areas — must be individually editable; a generated tree that becomes an authored element leaves the regenerable batch so it will not reappear in the next generation.
Interpretation declared as interpretation
The KML doesn't draw the full coastline or bound all the forest to the north: the strip of sand, the bay's water, the built-up area and the extensive vegetation were inferred from the captures and belong to the scenery layer, identifiable as approximations. Two POIs fall outside the inferred land (one Rio and the Pier) and get narrow boardwalks from the shore — a playable interpretation, not a Google Earth trace. Rivers and sea are surface representations, not water simulation. Names and routes are the author's annotations, not an official survey.
Code does the systematic work and doesn't hide visual decisions
After the migration, code remains responsible for importing the geography, fitting objects to the relief, distance-based loading, applying LOD, creating collisions, driving the day cycle and instancing large batches. Positions of houses, lampposts, authored trees and narrative points must not remain scattered as Vector3 inside world_builder.gd: the generator reads the saved composition. The success criterion is the author opening Godot, finding an object by name, moving it, saving and seeing the change in the game without editing coordinates or depending on AI.
Where the 2D and the valley disagree, the valley wins
The geography that exists is a real source, measured in KML, and is not altered to fit the 2D's layout; it is the quest step that adjusts, because the place is what the player sees and the step is text. The campaign already resolves plateau, bridge, ridge, boulder, farm and the ruins of the mansion in the valley; the ford is gone (the great river is deep and only the bridge crosses it), the corral became the chicken coop, and only the lagoon remains on the list of pending places. The geography preserves the village's relative layout and receives the anchors of the new quests.
The valley on October 5: sky, ground and daily life
A sky with the Milky Way, lowland mist and the bay horizon; eight ground layers blended by slope and elevation; woodland patches, clearings and distant crowns; yards, fields, houses, villagers by trade and wildlife with routines. The camera reacts to walls, ground, houses and rocks without jumping when passing a villager or prop.
9 rules
In practice, day to day
- Data layers: data/mapas/bom_jesus_dos_pobres_fonte.kml (original drawing, bytes preserved), bom_jesus_dos_pobres.json, bom_jesus_dos_pobres_cenario.json (interpreted coast, village and forest; reviewable) and regioes.json (catalog with active_region and scale_m_per_unit).
- When updating the drawing: re-export from Google Earth, check Placemark IDs, names and counts, replace the versioned source, run importar_kml.py and, if the masks changed, importar_mascaras_html.py; compare the top view with the drawing and walk the Square, coast, Bridge and Lookout in the game.
- IDs: the importer uses each Placemark's id attribute as the feature key; features without an id get 'provisional_…', which must not become a permanent key. The ExtendedData kind field can declare poi, road, river or area.
- Land with collision on both sides and double-sided materials (without this, physics couldn't see the Square's ground and the character fell through); streets with their own collision so they stay walkable where they cross water; water without surface collision, but the seabed has collision for swimming.
- Buildings use the geographic point as a reference, but the final position is searched for on land, with room for the whole building, clear of streets and trees, with the door facing the nearest street (lot layout); trees that would overlap a house are repositioned.
- Vegetation visibility distances: understory 85 u; restinga 200; river trees 230; coconut palms 250; forest canopy 280, with a 20 u anti-flicker margin; suspended on the orthographic maps (camera at 3,000 u) and on the minimap (100 u).
- The menu flyover is planned offline, flies 14.6–17.4 m above the ground with 5 m of clearance from the real geometry, and is checked by the tests/sobrevoo_livre*.gd gates; plant a tree or move a house and they fail: replan.
- The editable terrain preview is generated by tools/mapas/gerar_terreno_editavel.gd and replaced on every run: don't keep manual vertex edits in it until the separation between the imported base and authored adjustments exists.
- Villager posts and lines in data/npcs_3d.json (one post per period: morning, afternoon, dusk, night, small hours, each an anchor plus an offset); sunrise and sunset times in dia.gd; sky colors in world_builder.gd::_aplicar_hora; lights in _build_luzes_epoca.
Where it shows up
- The 12 KML points
Rio (two), Pedras, Pier, Cemitério, Ponte, Mirante, Igreja, Bar, Praça, Restaurante and Casa da estrada are the landmarks in the geographic source. The valley also resolves the campaign's new anchors; the map page distinguishes existing places from planned ones. - The triangular square and the houses facing the street
The square was enlarged to the shape of the real largo, with no vegetable garden in the middle (the beds moved to the edge), and eight more houses along the streets; the player's inherited house sits beside the field. - The sea of the nautical chart
Seabed shaped by DHN chart 1108 (intertidal zone, shallow shelf, slope and the Paraguaçu channel); transparent water colored by depth — greenish sand at the edge, jade in the shallows, petrol green in the channel, as in the aerial photo of Bom Jesus. On the shallow flat you can walk ~600 m out to sea. - Curving streets and crossings
The KML lines go through Chaikin (corners cut three times, up to ~100 m), the wider street sits on top at crossings, and each joint gets a patch of packed earth with an irregular edge; sand runs over the streets that reach the beach. - The map inside the game
The valley's top-down map uses the same geography as the scenery, with zoom, dragging and clickable markers. In the game, M opens it; from the menu, the Map button loads the valley and opens the map, with the painted map on the loading screen. - Saubara's local forest
Red mangrove swamp at the river mouth, ingá trees on the riverbanks, piassava palms and genipap trees in the woods, clusias and piassavas in the restinga, a pitanga tree in each house's yard and an understory of heliconias and bromeliads. Tree cards can be consulted with E and are kept in the almanac.
Where it comes from
The documents behind this area
- Authored composition — how the valley is edited in Godot
- Geographic map — the Google Earth drawing as reference
- The living valley — day and night, residents and the valley's sound
- 3D changelog — what changed in each build
- Development history — the steps before the standalone repository
- Valley clock — time of day, sun and light
- Bay tide — the sea rising and falling
- Places — each place's name and where it is