ewan's projects — docs
← all docs

isolith

August 12, 2026 4 min read
godotcsharpgameplatformeratprotoprocedural-generation

isolith is an isometric 3D platformer built with Godot 4.7 and C#. Jump between floating stone platforms, collect shards, and avoid the spikes. It's a game first — it plays offline, keeps its own local history, and needs no account — but can optionally sync your run stats into your own AT Protocol repo via wolfram.

Features

  • True isometric camera — orthographic, pitched to atan(1/√2), rotatable in 90° steps
  • Forgiving platformer feel — coyote time, jump buffering, variable jump height, separate rise/fall gravity
  • Gamepad-first controls — every menu is fully navigable with a stick and two buttons
  • Endless mode that adapts — sections are generated ahead of you and shaped by how the previous section went (dying eases difficulty, cruising pushes it); every generated jump is clamped to the character's jump envelope and proven reachable in the test suite
  • Levels as data — authored courses are JSON, built into geometry at load time
  • Course hazards — moving platforms, crumbling platforms, bounce pads, spike pits, checkpoints
  • Synthesised assets — every sound is generated by a script in the repo, every mesh built in code; sky/surface materials are CC0 packs fetched with pinned checksums
  • Local-first saves — every completed run is written to local history; settings are a hand-editable INI, and AT Protocol sync is entirely optional

Requirements

  • Godot 4.7 (.NET / Mono build)
  • .NET SDK 10.0
  • Python 3.10+ (only to regenerate audio)

Getting Started

git clone https://github.com/ewanc26/isolith.git
cd isolith
dotnet build

Open project.godot in Godot 4.7 (.NET) and press F5, or run directly with godot --path ..

The CC0 sky and material packs are committed, so there is nothing else to fetch. To re-pull or update them, run python3 tools/fetch_assets.py; to regenerate the committed sound effects, run python3 tools/generate_assets.py.

Controls

Action Gamepad Keyboard
Move Left stick / D-pad WASD / arrows
Jump A Space
Turn view 90° LB / RB, or flick right stick Q / E
Zoom Triggers + / -, mouse wheel
Restart course Y R
Pause Start Esc
Sync panel Back F1

Hold jump for height and release early to cut it short. Bindings live in src/Core/GameInput.cs rather than project.godot, so they stay readable in a diff.

Settings

Settings are reachable from the title screen and the pause menu, and are stored as a plain INI at user://settings.cfg. They cover master and effects volume, fullscreen, camera zoom, whether endless mode explains its difficulty changes, and — once a sync sign-in succeeds — the remembered handle and PDS. App passwords are never written to disk.

Endless Mode

Endless is the default mode: sections are generated ahead of you, and the director reacts to the section you just played. Dying shortens gaps and widens platforms; clearing cleanly stretches gaps toward the limit of what you can jump; repeatedly dying on moving platforms makes them rarer without softening the rest. The bottom of the screen explains each decision.

Difficulty falls faster than it rises on purpose. Every generated jump is clamped against an envelope derived from the character's tuning constants, so the generator cannot produce an impossible jump. Set Seed on the Main node to any non-zero value to replay a run exactly, or set Mode to Authored to play the hand-authored course instead.

Writing a Course

Drop a JSON file in courses/ and point GameManager.CoursePath at it. A course defines its spawn, kill plane, blocks, movers, shards, checkpoints, and goal. Block kind is one of Solid, Grass, Hazard, Bounce, or Crumble; positions are centres and sizes are full extents. A fully held jump clears about 2.4 m of height and 5.9 m of distance, so keep gaps inside that envelope.

Testing

godot --headless --path . res://scenes/Smoke.tscn

The smoke test loads and builds every course, checks the built scene matches the data, and verifies spawn, checkpoints, and goal are standable. It also proves generated jumps across the full difficulty range are reachable, that generation is reproducible from its seed, that the director eases after deaths and holds after near-misses, and that every menu control has a focus neighbour.

Stat Sync (Optional)

Run stats can be copied into your own AT Protocol repo as uk.ewancroft.isolith.run records via wolfram, through a P/Invoke wrapper in src/Sync/. Every completed run is saved locally first, unconditionally; sync is off by default, the game never prompts for it, and every failure is non-fatal.

To enable it, build libwolfram and drop it in native/ (see native/README.md), then press Back / F1 in game and sign in with your handle and an app password. The password is used for a single createSession call and is never written to disk; no session token is persisted either, so signing in is per-session by design. Runs carry a SHA-256 of the course JSON, so times stay comparable only within one version of a level. Only your own repo is read and written — there is no cross-user leaderboard.

Licence

Code is MIT — see LICENSE. Assets are additionally released under CC0 1.0; see ASSETS.md.


← all docs