Skip to content
vicPublic

Latest commit

 

History

185 Commits

Folders and files

Repository files navigation

ToT

Sponsor

ToT is made for agentic-gaming (ClaudeCode only) where you can ask an agent for a new adventure world and to spawn pals or foes.

ToT is a survival game that runs in your terminal. You are a lone hero in a dark dungeon. Foes come in waves, bosses come at times you don't want, and you grow strong enough to beat them or you do not. The game draws iso-view scenes with text glyphs, so it needs no graphics card and no window system.

Grow a skill tree per class, gear up from merchants, blacksmiths and jewelers, carry souls from run to run, and bring a crew of AI agents into the fight as pals or foes.

Each adventure is a set of data files: the foes, the bosses, the words, the colors and the art. The same engine plays all of them. Here are two runs, played by the built-in demo player. Each adventure defines the complete experience and can be generated by ClaudeCode agents locally.

Play it

Download From Releases

You need Nix with flakes on. Run the game from this repository without a checkout:

$ nix run github:vic/tot -- play

The command after -- goes to the game. With no command, the game prints its usage and exits.

The game needs a terminal that speaks the kitty keyboard protocol, so it can see held keys. Ghostty (1.4.0 or newer), kitty and Rio work. The terminal must be at least 120 columns by 40 rows. Use a small font. The game starts on a screen where you pick an adventure and a class.

To watch the game play itself, run the demo. It takes no keys and runs in any terminal:

$ nix run github:vic/tot -- play --auto --profile cyberpunk

The adventures that ship with the game are cyberpunk, dnd, hellish, kawai and moriah. Add --seed 7 to play the same run again.

Town, gear and legacy

Keepers stand in the rooms around your start. Walk up to one and its shop opens; the world waits while you shop. Every keeper sells items, and the keys 1 to 4 buy them. The merchant also buys back: x sells the first item in your bags. The blacksmith forges a rare item from ore with 5, and u raises the piece you wear in the chosen slot one plus, up to plus five, for gold and ore. Tab picks the slot. The jeweler puts an enchantment on that piece with e. Some keepers deceive you: a crooked smith can botch the work and keep your coin, and a crooked jeweler curses the piece instead.

Every run ends with souls: one for each ten kills, more for each level and boss, and many for a win. Souls stay when the hero dies. Press L at any time, also on the death screen, to spend them on boons in the legacy tree. Vitality, Might and Fortune are the roots; Swiftness, Kinship and Wisdom open at rank two of a root; Insight, the crown, opens at rank three of Wisdom. A boon holds from the next run on. The legacy is saved in ~/.local/share/tot/legacy.json.

Agentic crew

The game is also a chat room for agents. Press P, type what you want, pick a live local Claude Code session with Tab, and press Enter. The line goes to that session with the crew protocol and the state of the fight. The agent answers by sending JSON lines to the game's socket: it invents each crew member (its name, class, glyph, colour, hit points, pace and up to four abilities) and orders it about. A pal fights beside you; a foe hunts you. The engine knows no classes, only five verbs with numbers: heal, strike, blast, raise and taunt. So a healer, a tank, a necromancer or a battle mage is whatever the agent makes of them.

One prompt can field a whole team. An agent can spawn subagents and give them the game's address; the game answers whoever writes to it, so each subagent can run its own members and talk to the others through the game. Their chat shows in the lower left, the crew in the pane under the stats, and each member's name and last line over its head. The game reports back what the crew did, the lines it refused and why, and the state of the fight.

Pals roam on their own: each one walks between spots of its own near you, goes after foes near itself, and comes back when it strays too far. A bar over each pal and each boss shows its health; H hides and shows the bars. A pal you rescue in the dungeon joins your party with its own name, look and abilities.

An open world the agents direct

The engine holds no story. Under a safe town lie the deeps, level after level, linked by stairs; each level deeper has tougher foes. Once an agent is connected it runs the world. It names the levels, puts people in them, gives you quests and shows you scenes. A person has a job: it trades, forges, enchants, heals, or only talks. Walk up to one to meet it. A quest is a goal the engine counts (slay foes, win pals, reach a level) and a reward it pays when you are done. A scene is a card with the agent's words and up to four choices; the world waits while you read, and your choice goes back to the agent. The agent hears where you go, whom you meet and what you choose, and it acts on its own between your prompts. A dim line under the chat gives tips on playing with agents.

The task list under the crew shows every open quest with its progress, and for each objective on your level an arrow and the metres to it. Objectives are green on the map and on the screen edge. You follow one at a time: o picks the next, and a dotted line leads you to it (O hides the line). Portals (the stairs between levels) are big cyan blocks with big cyan arrows; shops stand on stalls of their own colour.

T opens the colour scheme picker: type to filter the 200-odd dark base24 schemes fuzzily, move with up and down, and the game repaints live as you go. Enter keeps the scheme (it is saved for later runs); Esc puts the old colours back.

An agent can also make each level what it wants: a safe haven or a dungeon, how deadly it is, and the colours of its floor and walls. It can take the horde over: switch off the built-in waves, send foes of any family, call a boss, release a treasure goblin, and point a pal at the foe it should kill first. It can even write a whole new adventure (classes, foes, items, words, colours and art), send it through the game's socket, and switch the game to it while you play; the link to the agents stays open across the switch.

To try it without a kitty terminal, run a headless fight. The autopilot plays the hero, and the run prints the chat:

$ tot agentic
$ tot crew --to 12345 --say "a healer and a tank for me, and a rival necromancer" --secs 120

tot agentic lists the live sessions and their process ids; give one to --to (12345 above is an example).

Static binary

The package static-tot is a static Linux build. It does not need Nix libraries at run time:

$ nix run github:vic/tot#static-tot -- play

Each release also has a tot-<system>.tar.gz for x86_64-linux and aarch64-linux. Unpack it and run the tot file inside. Keep the data directory next to it.

Keys

In play mode, wasd, hjkl or the arrow keys move the hero. A tap on Shift dodges. x hacks a foe. q and e turn the camera. : opens the command line, and Space opens the leader menu, which lists the next keys after a short wait. In the pick screen, h and l select a power, Enter takes it and s skips. t, i and b open the skill tree, the gear and the bags. P speaks to the agents and L opens the legacy. After a death or a win, r starts a new run and q quits. Every key is data in data/bindings.jsonl, so you can remap it.

Record the demo

The dev shell has vhs and the Rust tools. The tape in demo/ only starts the demo player and waits, so the game does all the work:

$ nix develop
$ vhs demo/cyberpunk.tape

Develop

Every tuning knob is in data/. A data file with a bad value fails at load, and the message names the file, the line and the path of the bad value. To run the tests:

$ nix develop -c cargo test --release
$ ./test.sh

test.sh also runs the linter and gives each test a time limit of one second. The bot player runs without a terminal, so you can test balance changes:

$ tot bot --seeds 16 --move kiter --pick tag

Run tot --help for the other commands.

Releases

Sponsor this project

Packages

Contributors

Languages