Orkuncakilkaya fb728bbefe chore(repo): DX cleanup — categorise examples, text-diffable golden, build/ output (#27 #28 #30 )

Repository-cleanup / DX pass folding three tracker items into one coherent
change, verified green end to end (`bin/x test` 49/0, `bin/x selfhost-test`
29/0, `bin/x test-tools` 29/0).

#28 — curate & categorise examples/
- 42 flat entries regrouped into intent-revealing subdirs: games/, rendering/,
  ecs/, events/, networking/, lang/, library/ (was lib/).
- chronorift dir-vs-file duplication resolved: the entry file and its import
  modules now live together under games/chronorift(.ludic).
- Every path reference updated repo-wide (test runner, editor-tool drivers,
  docs/site, design docs).
- New examples/README.md indexes the whole set with run commands.
- Showcase examples without a self-asserting entry (hello, events, net_rt) now
  get a compile-only rot guard in `bin/x test`, so nothing here rots silently.

#30 — text-diffable golden baseline
- The 4 binary selfhost/golden/*.ppm blobs are replaced by a single
  selfhost/golden/renders.sha256 manifest (SHA-256 per render). Hashes are
  byte-identical to the old PPMs, so the baseline is unchanged — only its form.
- game_case now compares framebuffer hashes; a regression shows as a changed
  hex line in review, not "binary files differ".
- New `bin/x golden` regenerates the manifest deliberately (review with
  `git diff selfhost/golden/renders.sha256`).

#27 — PPM & asset handling
- Headless renders now write build/out.ppm, never the repo root; `x app`,
  `x clean`, messaging and .gitignore updated to match. Nothing is written to
  the working root any more.
- Redundant local Kenney .zip archives removed (the art ships extracted;
  .gitignore already excludes *.zip). CC0 License.txt files retained.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-08-30 18:54:21 +03:00

5.9 KiB

Raw Blame History

Examples

A curated tour of Ludic, grouped by intent. Every example here is exercised by the test suite (bin/x test / bin/x selfhost-test), so nothing in this directory silently rots.

Run any program straight from the repository root (so assets/ resolves):

bin/x app examples/games/snake.ludic              # compile + open a real window
bin/x app examples/games/snake.ludic --headless   # render one frame to build/out.ppm
bin/ludic examples/lang/offline_rewards.ludic     # compile + run a plain program

`games/` — complete, windowed games

Example	What it shows
`games/snake.ludic`	A full game from primitives: input, grid, growth, collision, score.
`games/menu.ludic`	A retained-UI title screen — the UI declared as data.
`games/chronorift.ludic`	A 2D co-op JRPG: overworld, dungeon, random encounters, turn battle, boss, save. The entry file `import`s the modules under `games/chronorift/`.

`rendering/` — drawing primitives

Example	What it shows
`rendering/draw_prims.ludic`	The extended `Screen.*` primitives — line, circle, triangle, fill, sprite.

`ecs/` — the entity-component world

Example	What it shows
`ecs/hello.ludic`	The smallest program that exercises the ECS pipeline.
`ecs/world_get.ludic`	Reflection: read/write a component by name.
`ecs/world_scan.ludic`	Reflection: scan the world and identify each entity.
`ecs/world_query.ludic`	Reflection: iterate the world by property.
`ecs/world_spawn.ludic`	Reflection: a mod spawns a fresh entity by model id.
`ecs/world_mixed.ludic`	Reflection: get/set through real struct offsets.
`ecs/world_dyn.ludic`	Reflection: register a brand-new component at runtime.

`events/` — the event bus

Example	What it shows
`events/events.ludic`	EV0: the event-bus core — declare, `emit`, `@On`.
`events/mod_events.ludic`	Two listeners on one event, driven from a mod.
`events/cancel.ludic`	EV3: cancellable (decision) events.
`events/recurse.ludic`	EV6: re-entrant `emit` is depth-bounded — no runaway cycle.
`events/promote.ludic`	EV1: `@Public` promotes a lifecycle hook to a public event.
`events/prop_events.ludic`	EV1 for properties: attach/detach events.
`events/scene_events.ludic`	EV1 for scenes: on-enter / on-exit events.
`events/program_events.ludic`	EV1 for the program scope: start/quit events.
`events/layer_events.ludic`	EV1 for layers + a `public` layer's show/hide events.
`events/scoped.ludic`	A despawned entity drops out of subsequent event work.

`networking/` — deterministic multiplayer (N0–N6)

Each maps to a stage of NETWORKING-DESIGN.md; all run over the compiler's built-in loopback transport with zero foreign code.

Example	What it shows
`networking/net_echo.ludic`	N0: the transport seam.
`networking/net_snapshot.ludic`	N1: whole-world snapshot to a memory buffer.
`networking/net_sync.ludic`	N2: `@Sync` replication codegen.
`networking/net_owner.ludic`	N3: entity ownership.
`networking/net_rpc.ludic`	N4: remote events / RPCs.
`networking/net_roles.ludic`	N5: handler roles + the drivable sim.
`networking/net_demo.ludic`	N6: a networked game end to end, in pure Ludic.
`networking/net_rt.ludic`	A blessed server-authoritative replication runtime.

`lang/` — language & standard-library tour

Example	What it shows
`lang/annotations.ludic`	The annotation-first style: `@Queries` / `@Computed` / `@OnSpawn` / `@Handles`.
`lang/qdecl.ludic`	`@Queries` desugaring to the query system.
`lang/lifecycle.ludic`	The whole game lifecycle as `@`-hooks, in firing order.
`lang/detach.ludic`	Structural attach/detach + `@OnAttach` / `@OnDetach`.
`lang/reason.ludic`	Reason-carrying teardown (`@OnDespawn`: Despawned vs Quit).
`lang/toggle.ludic`	enable/disable at the three ECS scopes.
`lang/scenes.ludic`	One active scene at a time, handlers grouped into layers.
`lang/strings.ludic`	Strings as values: compare, join, interpolate, slice.
`lang/rng_demo.ludic`	The `Random.*` extensions (value/int/sign).
`lang/time_demo.ludic`	`Time.frame` / `elapsed` / `delta`.
`lang/offline_rewards.ludic`	A worked idle-game example over the Time/Date/Duration stdlib.

`library/` — building and linking a shared library

A how-to for compiling a .ludic module to a native .dylib/.so/.dll and linking a second program against it via extern fn:

bin/ludicc examples/library/combat.ludic --shared -o build/libcombat.dylib
bin/ludicc examples/library/arena.ludic  -o build/arena -Lbuild -lcombat

Example	What it shows
`library/combat.ludic`	Exported functions callable across the C ABI.
`library/arena.ludic`	A program that links against the shared library.

5.9 KiB Raw Blame History Unescape Escape

Examples

games/ — complete, windowed games

rendering/ — drawing primitives

ecs/ — the entity-component world

events/ — the event bus

networking/ — deterministic multiplayer (N0–N6)

lang/ — language & standard-library tour

library/ — building and linking a shared library