Skip to content

MARKDOWN SOURCE

Raw
# 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 <http://127.0.0.1:9999> (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 <page>`, `--full`, `--seed <n>`, and
`--strict` (fail on console errors too). Add `?seed=<n>` 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 <http://127.0.0.1:9999/tools/model-gallery.html> 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.

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:

mise run dev

The dev host and port live in mise.toml under [env]:

[env]
HOST = "127.0.0.1"
PORT = "9999"

Open http://127.0.0.1:9999 (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

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:

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.

HeroineRoleStarting cardsMarket cards
AislinnRanged support, range 3Mist Lance, Veil of Bran, Dream SnareWind Tales, Lullaby
FinellaMelee assassin, movement 4Crooked Blade, Venom Kiss, Blood for BloodStep Between, Widow's Due
AtlantaRanged hunter, range 4Hunter's Mark, Snare, Golden StagPiercing 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

InputAction
Click a green hexMove the active heroine
Click a red hexBasic attack that enemy
Click a card, then a highlighted hexPlay a targeted ability
Click a self-only cardPlay it immediately
1–6Pick a card from hand
SpaceEnd turn (or return to the village after a victory)
Esc / right-clickCancel aiming
R on the result screenFight 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

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.

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 <page>, --full, --seed <n>, and --strict (fail on console errors too). Add ?seed=<n> 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 http://127.0.0.1:9999/tools/model-gallery.html 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:

# 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.