# Torment A turn-based hex tactics battle with ability cards, rendered with Three.js. Three heroines — Aislinn the Dreamweaver, Finella the Assassin, and Atlanta the Huntress — stand against the Torment. Fights borrow the shape of a Heroes of Might & Magic battlefield rather than an auto-battler: units act in initiative order, movement and attacks share a turn, and each heroine's abilities are cards drawn from her own deck. ## Run it Requires Bun 1.4+ (pinned in `mise.toml`; run `mise install` first). There is no build step — Bun only serves the files and runs the tests: ```sh mise run dev ``` The dev host and port live in `mise.toml` under `[env]`: ```toml [env] HOST = "127.0.0.1" PORT = "9999" ``` Open (or `http://localhost:9999`). Change `PORT` there if the port is taken. Three.js is vendored under `vendor/`, so the game does not download anything at runtime. All art comes from the bundled `assets/` folder. The browser runs the same ES modules that Bun checks; nothing is bundled for play. ## Bundle for deployment ```sh bun run bundle bun run serve:dist ``` `serve:dist` also honours `HOST` and `PORT` from the mise environment when run through `mise exec`; it defaults to `127.0.0.1:9999`. `bun run bundle` writes a deployable `dist/`: - `app.js` — one minified ES module with Three.js, GLTFLoader, and the game - `index.html` — rewritten with no import map, pointing at `app.js` - `styles.css` - `assets/` — only the models, textures, portraits, and card icons the game uses The folder is self-contained; serve it from any static host. `dist/` is gitignored and can be rebuilt at any time. ## Hero models and animation The three heroine GLBs are authored procedurally with Blender 5.2. Each script builds the character from the shared parts in `tools/blender/hero_parts.py`, then `tools/blender/rig.py` adds a lightweight object-to-bone armature and exports Idle, Walk, Attack and Hit clips: ```sh blender -b --factory-startup -P tools/blender/aislinn.py -- --out assets/models/aislinn.glb blender -b --factory-startup -P tools/blender/finella.py -- --out assets/models/finella.glb blender -b --factory-startup -P tools/blender/atlanta.py -- --out assets/models/atlanta.glb ``` The game clones those models, drives the Armature with `THREE.AnimationMixer`, and layers its procedural lunge, projectile, slash and status effects on top. No external character assets are required. ## How a fight works - **Initiative.** Every living unit acts once per round, ordered by initiative (Finella 10, Atlanta 8, Aislinn 7, Silencer 6, Spitebound 5, Sorrowbrute 4). The turn strip at the top shows the current order. - **Movement.** A heroine may move up to her movement value in hexes. Green hexes are reachable; moving does not end the turn. Units block each other. - **One action.** After moving, a heroine may either make a basic attack or play an ability card. Attacking or playing a card ends her turn. - **Range.** Basic attacks use the heroine's range in hexes (melee 1, Aislinn 3, Atlanta 4). Enemies in range are highlighted in red. - **Retaliation.** A defender that survives a melee or ranged attack strikes back once per round for half its damage, if the attacker is within the defender's range. - **Fervor and cards.** Each heroine starts a battle with 2 fervor and gains 2 at the start of each of her turns (maximum 6). She starts with up to three of her owned cards in hand and draws one more each turn; played cards go to a discard pile that reshuffles when the deck runs out. Cards cost 1–3 fervor. - **Winning.** Break every Torment unit to win. If every heroine falls the encounter is lost. A battle that lasts 20 rounds is a draw. - **Enemy tactics.** The Torment hunts as a pack: it focuses the heroine it can most easily kill, finishes one a blow would break, values dangerous heroines over harmless ones, and never passes up an attack it can reach. Ranged enemies back off to the far edge of their range instead of trading blows in melee. Damage is reduced by armour and by wards; Hunter's Mark adds bonus damage after mitigation; poison ignores armour. Cards can also root, haste, heal, teleport, pierce a line of enemies, or splash around a target. ## Heroines and cards Each heroine has a five-card pool. A heroine starts with the three marked below and buys the other two in the village market. | Heroine | Role | Starting cards | Market cards | | --- | --- | --- | --- | | **Aislinn** | Ranged support, range 3 | Mist Lance, Veil of Bran, Dream Snare | Wind Tales, Lullaby | | **Finella** | Melee assassin, movement 4 | Crooked Blade, Venom Kiss, Blood for Blood | Step Between, Widow's Due | | **Atlanta** | Ranged hunter, range 4 | Hunter's Mark, Snare, Golden Stag | Piercing Shot, Volley | The draw order is seeded per battle. ## Campaign A new game asks you to choose one heroine to hold the gate. The other two wait in the village and can be recruited with honor. - **Honor** is earned for every Torment unit you break, even in defeat. Honor recruits heroines at the hall: Aislinn 40, Finella 60, Atlanta 50. - **Gold** is earned for every Torment unit you break, plus 30 for a victory. Gold buys cards at the market, at 30 gold per point of fervor (30, 60 or 90). Cards can only be bought for heroines already in your party. - **The level** is the Torment massing at the gate. It is the only encounter. You can fight it again as often as you like to earn more honor and gold. Heroines recruited later join the next battle with their starting cards. ## Saving and loading The title screen starts a new game or loads one of three save slots. In the village, **Save** and **Load** work the same way. During a battle, **Save** stores the fight exactly as it stands, including the shuffled decks. **Main menu** during a battle abandons it, with no honor or gold. Saves live in the browser's `localStorage` under `torment.save.0` to `torment.save.2`; clearing site data removes them. ## Controls | Input | Action | | --- | --- | | Click a green hex | Move the active heroine | | Click a red hex | Basic attack that enemy | | Click a card, then a highlighted hex | Play a targeted ability | | Click a self-only card | Play it immediately | | `1`–`6` | Pick a card from hand | | `Space` | End turn (or return to the village after a victory) | | `Esc` / right-click | Cancel aiming | | `R` on the result screen | Fight again | ## Layout ``` index.html screen shell and import map styles.css overlay UI styling src/hex.js hex-grid math (odd-row offset, distance, lines) src/catalog.js heroines, enemies, cards, encounters src/battle.js headless turn-based rules engine and enemy AI src/session.js title → village → battle → result flow, save and load src/profile.js honor, gold, party, owned cards, and battle rewards src/saves.js save slots in localStorage src/view.js Three.js battlefield and village menu, units, highlights, effects src/main.js DOM UI, input, and the animation loop src/assets.js asset paths shared by the view and the bundler scripts/serve.js Bun static file server scripts/shot.js screenshot and smoke-test harness scripts/check.js Bun build check for every browser module scripts/bundle.js produces the deployable dist/ bundle tools/model-gallery.html contact sheet of every GLB under assets/ tools/blender/ headless Blender build/export helpers and heroine sources tests/ Bun tests for the grid and rules engine vendor/ pinned Three.js module and GLTFLoader addons assets/ castle kit, textures, heroine models, and game icons heros/ character notes and a story page per heroine dist/ generated by `bun run bundle` ``` The rules engine has no renderer dependencies; `bun test` exercises it headlessly. ## Verification ```sh bun test bun run check ``` The tests cover initiative order, movement blocking, attacks and retaliation, every card effect, deck reshuffling, victory/defeat, enemy targeting and pathing, and session progression. ## Tooling Screenshot and modelling tools are dev dependencies (`bun install` after cloning). On a fresh machine also run `bunx playwright install chromium` once; the browser is cached in `~/.cache/ms-playwright`. `bun scripts/shot.js` boots the dev server (or reuses one already running), opens the game in Chromium, drives it through `window.torment`, and writes a PNG. It prints the scene state plus any console errors, page errors, or failed requests, so a visual check doubles as a smoke test. ```sh bun scripts/shot.js # title screen -> shots/menu.png bun scripts/shot.js village # the village -> shots/village.png bun scripts/shot.js shop # the market panel bun scripts/shot.js battle # the gate battle bun scripts/shot.js result # victory screen bun scripts/shot.js battle -e "document.querySelector('[data-card]').click()" --wait 400 bun scripts/shot.js models --full # every model -> shots/models.png bun --watch scripts/shot.js battle # re-capture on every save ``` Useful flags: `--headed` (real GPU window), `--scale 2` (HiDPI), `--frames 3 --every 400` (animation stills), `--url `, `--full`, `--seed `, and `--strict` (fail on console errors too). Add `?seed=` to any game URL to make a battle's shuffle and AI deterministic. `window.torment` exposes the session, view, and `start` / `transition` / `command` / `refresh` helpers for ad-hoc automation. Open to browse every GLB under `assets/` as labelled thumbnails with triangle counts and dimensions; `?q=` filters it. It is a dev page, not part of the bundle. ### Blender Blender 5.2 is installed at `~/.local/opt/blender` (`blender` is on `PATH`). All helpers run headless, so they work over SSH: ```sh # Export a .blend made in the UI (or by script) to a GLB the game can load. blender -b my-model.blend -P tools/blender/export_glb.py -- --out assets/models/my-model.glb # Build and export the example prop, to check the whole pipeline. blender -b --factory-startup -P tools/blender/example_prop.py -- --out /tmp/shard.glb # Rebuild the heroine models from their procedural sources. blender -b --factory-startup -P tools/blender/aislinn.py -- --out assets/models/aislinn.glb blender -b --factory-startup -P tools/blender/finella.py -- --out assets/models/finella.glb blender -b --factory-startup -P tools/blender/atlanta.py -- --out assets/models/atlanta.glb # The heroine scripts share their geometry helpers in hero_parts.py. # Inspect, validate, or optimise a GLB. bunx @gltf-transform/cli inspect assets/models/my-model.glb bunx @gltf-transform/cli optimize in.glb out.glb ``` After exporting under `assets/`, add the filename to `src/assets.js` if the game should load it, then capture `bun scripts/shot.js models` to see it beside the castle kit. Heroine models live in `HERO_MODEL_FILES`; the renderer replaces that heroine's procedural silhouette with the GLB whenever the file loads. ## Assets - Authored heroine models in `assets/models/`, built by the per-heroine Blender sources in `tools/blender/` on the shared `hero_parts.py` helpers. Each is about 15–28k triangles with no textures: - `aislinn.glb` — the pale dreamweaver of Lake Bala in a thin slip dress, bare feet in the lake mist, long moonlit hair, and floating orbs of mist. - `finella.glb` — the hooded assassin in dark leather, with a ragged cloak, gold buckles, a side braid, and twin daggers. - `atlanta.glb` — the huntress in a layered green tunic, with a feathered mantle, a quiver of arrows, and a tall recurve bow. - Modular castle objects and textures from the bundled `assets/castle_objects` kit (walls, towers, gate, trees, props). - Fantasy ground textures from `assets/textures_fantasy`. - Card and portrait icons from `assets/game_icons` (game-icons.net). - Three.js r187 is vendored under `vendor/` (MIT; see `vendor/THREE-LICENSE.txt`). ## Prototype limits All three heroines use authored GLBs; enemy units are still procedural silhouettes. There is no campaign persistence, town economy, or equipment. The old Rust / Bevy game code and its save format were removed; the repository now contains this web game plus the original asset library and character notes.