#skeleton

First milestone of the ftl-shape vertical slice. Establishes the Go + Ebitengine pipeline and a placeholder ship render that later milestones (crew-movement, systems-power, combat, polish) build on.

#Design

Purpose. Prove the Go + Ebitengine pipeline builds and runs on both desktop (macOS/Linux/Windows) and in-browser WASM, rendering a static placeholder player ship with 5 rooms in a ship-like layout. No interactivity. Foundation for every subsequent milestone.

In scope. Go module, Ebitengine main loop, virtual-resolution rendering, room data model, rectangle-based room rendering with labels, Makefile for native + WASM builds, minimal web/index.html shell, dev server via wasmserve, one-command "run in browser" target.

Out of scope. Input, crew, animation, enemy ship, sound, combat, menus, save system, disk-loaded assets, WASM size optimization.

Chosen approach.

• Rendering. Virtual resolution 640×360; window opens at 1280×720 (2× scale). Ebitengine's Layout returns 640×360; all drawing in virtual pixels. Resizable window is fine — Ebitengine handles scaling.
• Project layout. Single package at module root (sourcecraft.dev/bigbes/ftl-shape). Files by concern:
  • main.go — entrypoint, Game struct, Update/Draw/Layout methods.
  • ship.go — Ship, Room types, placeholder ship constructor.
  • render.go — drawing helpers (rect fill, border, label).
• Ship model. Ship{Rooms []Room} and Room{ID, Name, GridX, GridY, GridW, GridH, Role} in tile units. Render layer converts tile→virtual pixels at 16 px/tile.
• Placeholder ship content. 5 rooms — Pilot (front/left), Weapons (mid-upper), Shields (mid-center), MedBay (mid-lower), Engines (rear/right). Each rendered as a role-tinted filled rectangle + 1-px border + role label via Ebitengine's default text face from text/v2.
• Build tooling — Makefile targets.
  • run — native, go run ..
  • build — native binary to bin/ftl-shape.
  • build-wasm — produce web/main.wasm; copy wasm_exec.js from the installed Go toolchain ($(go env GOROOT)/lib/wasm/wasm_exec.js on Go ≥1.24).
  • play-web — one-command "run in browser": start wasmserve (auto-rebuilds on source change), print http://localhost:8080, and auto-open the browser (open on macOS, xdg-open on Linux, print-only otherwise).
  • serve — same as play-web without the auto-open step.
• Browser shell. web/index.html loads wasm_exec.js + main.wasm using the standard Go WASM snippet. .gitignore excludes bin/ and web/main.wasm.

Tradeoffs that settled the decisions.

• Grid-based rooms over freeform pixel coords: aligns with FTL's movement model; simplifies future click-to-move milestone.
• Single package over cmd/ + internal/: small surface area, minimum friction. Split when a file crosses ~300 lines or a real subsystem boundary emerges.
• Virtual resolution over native drawing: crisp pixel art at any window size; resizable-safe. Cost is a single Layout decision — negligible.

Unknowns. WASM binary size for Ebitengine builds is typically 10–20 MB. Acceptable for dev; optimization is out of scope.

TDD: no — skeleton is a visual + build-pipeline proof. Ship/Room are trivial data structs with no logic to assert; success is "window opens, rectangles appear, WASM loads in browser." TDD applies at the crew-movement milestone where pathfinding has real behavior.

#Invariants

• All drawing uses virtual-resolution coordinates (640×360). No code draws in window-pixel units.
• Single codebase builds unchanged for GOOS=js GOARCH=wasm and native targets; no platform-conditional imports (//go:build, GOOS-suffixed files) in this milestone.
• Room positions and sizes are stored in tile units on Room. Pixel conversion happens only at render time.
• No external asset files in milestone 1 — all placeholder art is code-drawn (filled rects + default text face).
• ship.go does not import Ebitengine. Data types know nothing about rendering.

#Principles

• YAGNI: no sub-packages, no interfaces, no ECS until a file crosses ~300 lines or a clear boundary emerges.
• Fail fast on init errors (WASM bootstrap, font load). Panic is acceptable; no silent fallbacks.
• Deterministic rendering: same ship state → same pixels. No hidden randomness in this milestone.
• Separate data from rendering: ship/room types never call the renderer and never hold Ebitengine state.

#Plan

Approach: two phases — first gets a native window rendering the placeholder ship, second adds the WASM build and the one-command browser target. Each phase is a self-contained runnable checkpoint.

Backwards-compat: greenfield project, nothing to break.

#Phase 1 — Native app rendering the placeholder ship

• 1.1 go.mod (modify)

  • Add dep github.com/hajimehoshi/ebiten/v2; run go mod tidy.

• 1.2 ship.go (create)

  • Package main.
  • type RoomRole int with constants RolePilot, RoleWeapons, RoleShields, RoleMedBay, RoleEngines.
  • type Room struct { ID int; Name string; GridX, GridY, GridW, GridH int; Role RoomRole } — tile-unit coords only.
  • type Ship struct { Rooms []Room }.
  • func NewPlayerShip() Ship — hard-coded 5-room layout: Pilot front-left, Weapons mid-upper, Shields mid-center, MedBay mid-lower, Engines rear-right.
  • Invariants: no Ebitengine imports in this file; positions and sizes in tile units only.

• 1.3 render.go (create)

  • Package main. Constants TilePx = 16, VirtualW = 640, VirtualH = 360.
  • func roleColor(role RoomRole) color.RGBA — role → tint mapping (mapping lives here, not in ship.go).
  • func drawShip(screen *ebiten.Image, s Ship) — iterates rooms, delegates to drawRoom.
  • func drawRoom(screen *ebiten.Image, r Room) — fills role-tinted rect, draws 1-px border, writes role name via ebitenutil.DebugPrintAt positioned inside the room.
  • Invariant: all coordinate math converts tile → virtual pixels through TilePx; no window-pixel math.

• 1.4 main.go (create)

  • Package main. type Game struct { ship Ship }.
  • func (g *Game) Update() error — returns nil.
  • func (g *Game) Draw(screen *ebiten.Image) — fills dark background, calls drawShip(screen, g.ship).
  • func (g *Game) Layout(int, int) (int, int) — returns VirtualW, VirtualH.
  • func main() — ebiten.SetWindowSize(1280, 720), ebiten.SetWindowTitle("ftl-shape"), ebiten.RunGame(&Game{ship: NewPlayerShip()}), panic on error.
  • Invariant: no platform-conditional imports; single build source for native + WASM.

• Commit: scaffold game loop and placeholder ship render

#Phase 2 — WASM build and browser run target

• 2.1 Makefile (create)

  • Targets: run, build, build-wasm, serve, play-web, .PHONY line.
  • build: go build -o bin/ftl-shape ..
  • build-wasm: GOOS=js GOARCH=wasm go build -o web/main.wasm . then cp "$$(go env GOROOT)/lib/wasm/wasm_exec.js" web/wasm_exec.js (Go ≥1.24 path).
  • serve: go run github.com/hajimehoshi/wasmserve@latest . — wasmserve rebuilds wasm on source change and serves on :8080.
  • play-web: detect OS (uname), background-delay open/xdg-open http://localhost:8080, then invoke the same wasmserve command.

• 2.2 web/index.html (create)

  • ~20-line WASM loader: <script src="wasm_exec.js">, instantiate new Go(), WebAssembly.instantiateStreaming(fetch("main.wasm"), go.importObject).then(r => go.run(r.instance)). Canvas set to 1280×720.
  • Used by any static-serve path; wasmserve generates its own index when running the dev loop, so this file is for future release hosting and not on the play-web critical path.

• 2.3 .gitignore (create)

  • Exclude bin/, web/main.wasm, web/wasm_exec.js.

• Commit: add Makefile, WASM loader shell, play-web target

#Test strategy

No automated tests (per TDD: no). Manual acceptance:

• Phase 1: go run . → window opens showing 5 labeled, colored rooms on a dark background.
• Phase 2: make play-web → browser tab at :8080 shows identical render; make build produces a runnable bin/ftl-shape.

#Open questions / risks

• wasm_exec.js at $GOROOT/lib/wasm/ — confirmed present for Go 1.26.2 (user's toolchain). Would fail loudly on Go <1.24; acceptable per design's fail-fast principle.
• WASM binary size (~10–20 MB) — known and out of scope per Design.

#Verify

Result: passed

Positive:

• go build ./... → clean
• go vet ./... → clean
• GOOS=js GOARCH=wasm go build → produces valid wasm (WebAssembly MVP, ~12 MB)
• make build → bin/ftl-shape Mach-O arm64
• make build-wasm → web/main.wasm + web/wasm_exec.js copied from $GOROOT/lib/wasm/
• make -n play-web → recipe expands to platform-detected open + wasmserve .
• Native binary smoke: ran bin/ftl-shape 2s in background, window alive, clean kill
• Browser smoke: served web/ via python3 -m http.server, loaded in Chrome, WASM instantiated and rendered 5 colored rooms with labels (Pilot, Weapons, Shields, MedBay, Engines) on dark background at 1280×720. Console shows only a benign 404 for favicon.ico.

Invariants:

• ship.go has no Ebitengine import (grep returned empty)
• No //go:build directives, no platform-suffixed *_js.go / *_windows.go / *_linux.go / *_darwin.go files
• TilePx references confined to render.go — pixel conversion happens only at render time
• No external asset files (png/jpg/wav/ttf/otf) anywhere in the repo
• git status clean after make build + make build-wasm — .gitignore correctly excludes all artifacts

#Conclusion

Outcome: skeleton milestone delivered — native window and browser WASM both render the 5-room placeholder ship at c71f238.

Invariants:

• All drawing uses virtual 640×360 — TilePx references confined to render.go.
• Single codebase for native + WASM — no //go:build, no platform-suffixed files; GOOS=js GOARCH=wasm go build passes.
• Tile-unit storage, render-time pixel conversion — Room fields are pure ints; conversion in drawRoom only.
• No external asset files — repo contains no image/audio/font binaries.
• ship.go free of Ebitengine imports — verified by grep.

Future work:

• Design prose mentions text/v2 for labels while Plan + code use ebitenutil.DebugPrintAt; harmless doc drift, reviewer flagged sub-threshold. Justification: Plan was the contract and was approved with the DebugPrintAt choice; swap to text/v2 + real face is a polish-milestone concern, not skeleton.
• Git init was done inline before Phase 1 (task file predates any branch/worktree workflow); future milestones should set **Branch:** / **Worktree:** headers up front.