Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Farlanding is a single-player 3D real-time strategy game about a survey expediti
beyond familiar space. Build bases, command a growing force, and uncover a trail
of discoveries that changes what your expedition can do. Made with Godot and Blender.

**[Play in your browser](https://farlanding.vercel.app)** ·
**[Play in your browser](https://farlanding.app)** ·
[Player guide](docs/PLAYER_GUIDE.md) · [Development plan](docs/PLAN.md)

![The Meridian in orbit above the expedition's first world](docs/media/browser-orbit.png)
Expand Down
11 changes: 10 additions & 1 deletion docs/ART_STYLE.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,9 @@ diffable and rebuildable.
| `art/pipeline/build_all.py` | Rebuilds every model and the palette |
| `art/pipeline/build_icons.py` | Renders a HUD icon per model into `game/assets/icons/` |

Rebuild everything: `blender -b -P art/pipeline/build_all.py`.
Rebuild models and palette: `blender -b -P art/pipeline/build_all.py`.
Terrain recipes under `art/terrain/` and HUD icon rendering through
`art/pipeline/build_icons.py` are separate steps; rebuilding models does not rebuild them.

### Texturing: one palette for the whole game

Expand Down Expand Up @@ -70,3 +72,10 @@ cyan instrument lamps. Orange marks warnings. `HudStyle`, `PlateStyle` and
before screens are built. Chakra Petch supplies body, button and heading weights.
Its SIL Open Font Licence is bundled under `game/assets/fonts/OFL.txt`, included
in exports and displayed in Credits.

## Application icon

`game/assets/branding/farlanding_icon.svg` is the editable favicon source. Its amber
landing chevron and cyan planet rim use the HUD palette. Rebuild the committed 512px
PNG with `game/assets/branding/render_icon.sh` (requires `rsvg-convert`, from librsvg).
The application icon setting supplies native icons and the Web export's browser icon.
30 changes: 25 additions & 5 deletions docs/CONVENTIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ Short rules for everyone writing code in `game/`. The why lives in `docs/PLAN.md
## Before you push

Run `tools/check.sh`. It runs format check, lint, headless import, a script-error check, the
unit tests and a boot of the main scene, and must exit 0. CI runs the same script.
unit tests, every-mission smoke, Python tooling tests and source/asset integrity checks.
It must exit 0. CI runs the same script. Engine and GUT warnings/deprecations fail the gate.

- Format: `cd game && uvx --from gdtoolkit==4.5.0 gdformat .`
- Tests: `godot --headless --path game -s res://addons/gut/gut_cmdln.gd`
Expand All @@ -28,9 +29,12 @@ unit tests and a boot of the main scene, and must exit 0. CI runs the same scrip

core <- sim <- ai / missions <- presentation / ui / audio

A folder may use anything to its left, never to its right. `sim/` never references a UI node, a
sound or a particle: it emits typed signals on `Events` (or its own nodes) and presentation,
UI and audio listen.
Simulation **scripts** must not depend on UI, audio or presentation scripts;
`tools/project_integrity.py` checks adapter class/path references. Simulation emits typed
signals on `Events` (or its own nodes), and adapters listen. Entity **scenes** may compose
simulation and visual children. `Main` and `LandingMap` are composition roots: they wire
the layers and provide dependencies before children enter the tree. Scene composition
does not imply that simulation code may call its visual children.

## Architecture rules in practice

Expand All @@ -39,7 +43,9 @@ UI and audio listen.
- **Gameplay runs on `SimClock` ticks (10 Hz)**, not in `_process`. Visuals interpolate with
`SimClock.get_interpolation_fraction()`.
- **Mission-scoped things hang off `MissionContext`**, never an autoload. Autoloads are only
`Events`, `Game`, `Settings` (and later `Audio`, `Save`).
`Events`, `Game`, `Settings`, `Audio` and `UiTheme`; the editor integration also
installs `MCPRuntimeProbe` (disabled by release feature, see the Web runtime ADR).
`SaveSlots` is a static service, not an autoload.
- **Definitions are data**: new unit types are new `UnitDef` `.tres` files, not new code.
- **Composition over inheritance**: an entity is a thin root plus component nodes.
- **Saveable from day one**: any class that holds gameplay state has `to_dict()` /
Expand All @@ -61,3 +67,17 @@ UI and audio listen.
- Commit `*.import` and `*.uid` files; never commit `.godot/`.
- Binaries go through Git LFS once it is enabled (see `.gitattributes`).
- Record expensive-to-reverse choices as a short ADR in `docs/adr/`.

## Ownership and cleanup

- A scene owns its child nodes. Configure dependencies before `add_child()`, which runs `_ready()`.
- A RefCounted fixture does not own nodes it attaches elsewhere: retain the fixture and call
its `dispose()` in `after_each`. Use GUT's autofree helpers only when they actually register ownership.
- A service that creates server RIDs releases them explicitly (`PathService.release()`).
Keep cleanup with the owner, including navigation, traffic registration and shader globals.
- Restore snapshots in dependency order: identities before references, planetary conditions
before path-dependent orders. Preserve the save version unless the serialized shape changes.
- Audio source recipes own generated streams and import sidecars; existing SoundEvents own
hand-tuned mix values. `project_integrity.py` checks hashes/inventory without regenerating audio.
Recipe edits also need the deterministic `audio_src/build.py --check` command documented in
`docs/AUDIO_PROVENANCE.md`; encoder versions can affect output hashes.
84 changes: 84 additions & 0 deletions docs/MAINTAINABILITY_PLAN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# Project maintainability improvements

Baseline: `593b8a5`. The audit covered game code, test ownership, tooling, CI,
asset pipelines and architecture documentation. Preserve gameplay, save formats,
resource paths, rendering quality and the tested-artifact deployment pipeline.

## Phase 1: make diagnostics trustworthy

Dispose the Verdance test fixture explicitly, replace deprecated GUT frame waits
with their identical physics-frame successor, and reject GUT warnings and
deprecations alongside engine diagnostics. Share diagnostic classification between
checks and exports. Run Python tooling checks locally as well as in CI.
Proof: diagnostic fixtures, focused Verdance run and complete native checks.

## Phase 2: fix runtime defects before restructuring

Reproduce placement over blocking props, then include public map obstacles without
revealing unseen enemy buildings to AI. Validate malformed save containers and
resource types before replacing the running landing. Preserve legacy saves.
Proof: focused failing-before regressions, placement commands and save round trips.

## Phase 3: clarify responsibilities

Use the existing LandingMap contract in Main instead of reflective property access.
Split world restoration into named ordered phases without exposing its registries.
Separate one-shot playback pools from mission/music orchestration in Audio while
preserving its public API, randomness, voice budgets and shutdown behavior.
Proof: mission/pause/save tests, planetary round trips and real-mixer audio tests.

## Phase 4: maintain the boundaries

Document actual composition roots and scene composition, fixture/node/RID ownership,
and the current autoloads. Add inexpensive asset manifest and simulation dependency
checks. Clarify separate art rebuild pipelines and hand-tuned audio resource ownership.
Keep third-party addons unchanged and avoid bulk asset regeneration.

## Phase 5: qualify and release

Run complete native checks, every-mission smoke, browser gameplay/persistence and
real-mixer qualification. Measure any proposed performance optimization against the
same scenario; ship only justified changes with unchanged visual settings. Obtain an
independent Sol review, resolve CI/bot findings, merge normally and verify both staged
and public Vercel deployment of the exact merge commit.

Menu navigation includes direct title-screen loading with Back/Escape return paths.
The browser launcher retains a deliberate Play gesture for browser audio, uses the
field-equipment palette, and places clearly explained graphics overrides under Launch options.
The README play link is https://farlanding.app; verify that domain after release.

The favicon is a separate visual addition. Keep its source editable and include a
Godot-compatible raster icon; do not couple it to runtime architecture.

## Research basis

Godot recommends focused scenes/classes and parent-provided dependencies:
[Scene organization](https://docs.godotengine.org/en/stable/tutorials/best_practices/scene_organization.html).
Its [project organization guidance](https://docs.godotengine.org/en/stable/tutorials/best_practices/project_organization.html)
supports consistent paths and isolated third-party addons, rather than gratuitous moves.
[Static typing](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/static_typing.html)
improves diagnostics and enables optimized operations. Ref's primary-source
[GDScript analyzer reference](https://github.com/godotengine/godot/blob/master/modules/gdscript/README.md)
explains the limits of dynamic access and the role of typed interfaces.

Do not rewrite the command queue, fixed-tick simulation, navigation cutter/traffic,
resource-driven definitions or platform rendering/audio adapters. A broad rewrite
would increase migration risk without an observed defect or measured benefit.

## Added gameplay slice: selling buildings

Add a tick-driven sell command and a selected-building action with refund preview
and confirmation. Completed placeable buildings return half their construction
cost; unfinished sites cancel for a full refund. Refund queued production through
the existing cancellation rule. Protect other factions, the Lander and story
machines. Prove single refunds, queue cleanup, immediate snapshot removal and
navigation/power/vent release, then verify the visible browser flow.

## Added exploration slice: remove advance discovery markers

Remove floating discovery question marks and unresolved-site minimap icons. Show
site models once their ground is explored, preserve scanning/rewards and chain
availability, and record only completed player surveys on the minimap. Update
onboarding and orbital-preview copy. ADR 0023 records this user-requested decision.
Proof: unknown versus explored visibility, enemy versus player map records, scan
feedback, saved vision, and browser screenshots on the actual maps.
20 changes: 19 additions & 1 deletion docs/PLAYER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Detailed controls and mission rules follow, including planet-specific mechanics.

**New campaign** puts you aboard the *Meridian*, the expedition carrier. The star map
shows the route of landings: hover one for its orbital scan (planet, rule, mission
type, unresolved `?` signals), click an open one and press LAUNCH. A won landing banks
type and survey context), click an open one and press LAUNCH. A won landing banks
the Intel you still hold when it ends (a lost one banks nothing, but its finds stay in
the Survey Log) and opens the landings it leads to; the route branches, and taking one side
closes the other. On the Meridian (MERIDIAN on the star map) spend banked Intel on the
Expand Down Expand Up @@ -74,3 +74,21 @@ KEYS. **How to play** and **Credits** are on the title screen.
On narrow windows or larger interface scale, the command strip scrolls sideways
to keep the minimap and selection information clear. Drag its scrollbar or use
horizontal scrolling to reach later build and production options.

From the main menu, **Load game** opens all usable landing saves directly. **Continue**
resumes the latest saved state directly: the landing, or the campaign between missions. In the slot screen, **Back** or
**Esc** returns to the menu you came from; an empty or damaged slot cannot be loaded.

The browser's **Launch options** override graphics only. **Use saved graphics** keeps
your settings, or starts on High on your first visit. Graphics, sound and controls are
available in the in-game **Settings** menu after launching.

Discovery locations are not marked in advance. Explore the terrain and look for unusual
structures and formations. Select a Surveyor and command it to scan a site you find.
A completed survey adds a coloured record to the minimap and an entry to the Survey Log.

Select one of your placeable buildings to **Sell** it. The button previews the Alloy
and Flux returned; click it again to confirm, or choose Cancel. Finished buildings
return 50% of their cost. Cancelling an unfinished site returns its construction cost,
and queued units are refunded using the normal cancellation rule. The Lander and
Antecedent story machines cannot be sold.
7 changes: 7 additions & 0 deletions docs/WEB_DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,3 +99,10 @@ a push-to-`main` workflow while its tested artifact is retained, or rerun that e
to create a fresh artifact. Manual **Run workflow** runs remain test-only.
Existing ready deployments can still be promoted or rolled back without
downloading the source artifact again.

## Browser launcher

The Play gesture follows Godot's [Web audio autoplay guidance](https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_web.html#audio).
Launch options overrides only graphics: the default keeps saved settings, or High on a
fresh profile. Full settings stay inside the game. The custom shell lives in
`game/platform/web_shell.html`; the exported `index.icon.png` comes from the application icon.
10 changes: 10 additions & 0 deletions docs/adr/0002-lint-and-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,13 @@ all of it.

If a future GDScript feature is not parsed by gdtoolkit, either avoid it or exclude that file in
`gdlintrc`/`gdformatrc` and note it here.

## Verification note (2026-11-15)

Only the explicitly stored warning overrides are project policy; engine defaults
supply other settings. The earlier list overstated the committed configuration:
`inference_on_variant` and `directory_rules` are engine defaults rather than explicit
overrides in this checkout. Verified through the running 4.7.2 editor: inference is
level 2 and directory rules are `{ "res://addons": 0 }`, matching the intended policy.
The script/resource load check and actual project settings remain the executable authority. Engine and GUT diagnostic classification is now shared
by local checks and exports; GUT warnings and deprecated APIs also fail checks.
13 changes: 13 additions & 0 deletions docs/adr/0013-save-and-load.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,3 +144,16 @@ camera looks where it did.
versions keep reading their older dictionaries.
- Not saved: commands younger than a tick, transient AI timers, and the shooter of a
projectile in flight.

## Continue and explicit Load game (2026-11-15)

The title now offers Load game for choosing a slot. Continue resumes the newest
readable landing directly when it is the latest saved state. A newer campaign
save between landings continues there. A campaign that already records a landing as won continues
on its star map or ending; old manual landings remain available through Load game.
With no usable landing, Continue falls back to the campaign save.

Slot payloads may include optional integer `write_order` metadata to break equal
whole-second `saved_at` timestamps by actual write order. Legacy files default to
zero, older builds ignore the extra key, and the save format stays at 2. The displayed
date still uses the original seconds value. No world/component schema changes.
23 changes: 23 additions & 0 deletions docs/adr/0023-discovery-exploration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# 0023 — Find discoveries through exploration

- Status: accepted
- Date: 2026-11-15

Discovery sites previously showed floating question marks and minimap markers even
under unexplored fog. Those location spoilers undermined the expedition's exploration.

Unresolved sites now read through their physical models after their ground is explored.
There are no floating question marks and no unresolved-site minimap icons. Completed
player surveys leave coloured minimap records; enemy surveys do not reveal locations.
Scan rings, progress beams, resolved glows, Intel and Survey Log rewards remain.
Orbital campaign previews provide context without revealing the unknown site count.
Survey objectives retain their text and progress, but have no location ring or beacon,
including when an older save carries the former area marker.

`charted` continues to gate discovery chains and simulation scanning availability.
It no longer means the player receives a free location marker. World visibility comes
from the existing persisted VisionGrid, so no new save schema is required. Audio still
uses current sight rather than the explored-ground memory.

Proof: unknown/explored/remembered site visibility, player versus enemy map records,
restored vision and scan-feedback tests, followed by real-map/browser qualification.
6 changes: 4 additions & 2 deletions game/ai/commander.gd
Original file line number Diff line number Diff line change
Expand Up @@ -729,12 +729,14 @@ func _explored_nodes() -> Array[ResourceNode]:
return found


## Placement rules over what the faction may know: terrain, bounds, its own
## buildings, the enemy buildings it remembers seeing, sites refused lately, and the
## Placement rules over what the faction may know: public terrain and prop obstacles,
## bounds, its own buildings, the enemy buildings it remembers seeing, sites refused
## lately, and the
## resource nodes it has explored. Never the live footprints of unseen buildings; the
## real rules still judge the PlaceBuildingCommand when it runs.
func known_placement_rules() -> PlacementRules:
var rules: PlacementRules = world.placement_rules()
# Only replace building knowledge; public prop obstacles stay in rules.obstacles.
rules.footprints = []
for building: Building in world.buildings_of(faction):
rules.footprints.append(building.footprint())
Expand Down
Binary file added game/assets/branding/farlanding_icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
40 changes: 40 additions & 0 deletions game/assets/branding/farlanding_icon.png.import
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
[remap]

importer="texture"
type="CompressedTexture2D"
uid="uid://dhu3anoxvpjhl"
path="res://.godot/imported/farlanding_icon.png-d2a66f47fe0fceafab76d4096b880989.ctex"
metadata={
"vram_texture": false
}

[deps]

source_file="res://assets/branding/farlanding_icon.png"
dest_files=["res://.godot/imported/farlanding_icon.png-d2a66f47fe0fceafab76d4096b880989.ctex"]

[params]

compress/mode=0
compress/high_quality=false
compress/lossy_quality=0.7
compress/uastc_level=0
compress/rdo_quality_loss=0.0
compress/hdr_compression=1
compress/normal_map=0
compress/channel_pack=0
mipmaps/generate=false
mipmaps/limit=-1
roughness/mode=0
roughness/src_normal=""
process/channel_remap/red=0
process/channel_remap/green=1
process/channel_remap/blue=2
process/channel_remap/alpha=3
process/fix_alpha_border=true
process/premult_alpha=false
process/normal_map_invert_y=false
process/hdr_as_srgb=false
process/hdr_clamp_exposure=false
process/size_limit=0
detect_3d/compress_to=1
Loading
Loading