Alchemy TUI

A terminal alchemy crafting game with a 755-element recipe book, and pixel-art sprites.

Table of contents

• What is Alchemy?
• Quick start
• User guide
• How the screen works
• How to play
• Tutorial: make Steam
• Responsive layouts
• Maintain the project
• Release checklist

What is Alchemy?

Alchemy games are discovery puzzles. You start with a tiny set of elements, combine two at a time, and unlock new ingredients when the pair has a recipe.

tui-alchemy starts with the four classical elements:

Starter	Use it to discover
Air	weather, motion, atmosphere, pressure
Earth	minerals, terrain, tools, life chains
Fire	heat, energy, lava, steam, metal chains
Water	mud, steam, oceans, life, weather chains

The core rule is always:

ingredient + ingredient = result

Early examples:

Water + Fire = Steam
Water + Earth = Mud
Earth + Fire = Lava
Air + Earth = Dust
Air + Fire = Energy

Every discovery is added to the atlas immediately, so the puzzle expands from four starters into a 755-element catalog.

Quick start

Install the latest release:

curl -fsSL https://i.tui-alchemy.sh | sh

The installer uses prebuilt binaries first, so Rust, Cargo, Python, Git, and a compiler toolchain are not required. It checks for small runtime tools such as tar plus curl or wget; when one is missing, it asks before installing it with the available package manager. If you already have Cargo, the published package is also available with cargo install tui-alchemy --locked; see docs/install.md.

Then run:

tui-alchemy

Command-line help and package metadata:

tui-alchemy --help
tui-alchemy --version

For local development from this repository:

cargo run

Press q to quit.

User guide

The player-facing README lives at docs/README.md. It includes the minimal in-game menu, the controls submenu, reset flow, and screenshot tables for the main play loop and responsive layouts.

How the screen works

Use it as a three-step loop: select an element → select a second element → get a result.

The left rail tracks progress, the center atlas holds discovered ingredients, and the right workbench resolves ingredient + ingredient = result.

How to play

Keyboard controls

1. Move through the atlas.
2. Select the first ingredient.
3. Select the second ingredient.
4. Watch the recipe table resolve the pair.
5. Use the newly discovered result as another ingredient.

Key	Action
Arrow keys	Move through the atlas
h, j, k, l	Vim-style atlas movement
Enter	Select the highlighted element
1-9	Select a visible atlas slot directly
PageUp, PageDown	Move atlas pages
[, ]	Move atlas pages
Home, End	Jump to the first or last visible discovery
Esc, c	Clear the current selection
m	Open the game menu; use controls for key help or reset game to restart discoveries
q	Quit

Mouse controls

1. Click or drag an atlas card.
2. Drop it into the first or second recipe-table slot.
3. Drop a second ingredient into the remaining slot.
4. If the pair is a recipe, the result appears and joins the atlas.

Tutorial: make Steam

Start from a fresh game:

1. Select Water.
2. Select Fire.
3. The workbench resolves Water + Fire = Steam.
4. Steam appears in the result slot.
5. Steam is added to the atlas and can be used in later recipes.

After Steam, keep branching through low-level recipes:

Water + Earth = Mud
Earth + Fire = Lava
Air + Earth = Dust
Air + Fire = Energy
Water + Water = Puddle
Earth + Earth = Land

If a pair does nothing, keep experimenting. Some elements become useful only after you discover deeper ingredients.

Responsive layouts

The UI is designed to remain playable across narrow, short, wide, and tall terminal sizes. The release screenshots in docs/screenshots/ are deterministic visual QA fixtures.

Narrow terminal	Large terminal

Additional layout captures:

• docs/screenshots/07-height-24.png
• docs/screenshots/08-height-48.png

Project layout

src/                    Rust application, renderer, layout, catalog, and sprite code
assets/pixel-sprites/   Runtime pixel-art sprite atlas and manifest
data/little_alchemy.json
                        Canonical 755-element recipe catalog
docs/screenshots/       Curated screenshots used by this README and release notes
scripts/                Screenshot, website build, installer, and Cloudflare deployment scripts
tests/                  Gameplay, layout, rendering, and regression tests
website/                Standalone site source for tui-alchemy.sh

Maintain the project

Use the narrowest check that covers your change, then run the complete release lane before publishing.

Code and gameplay

cargo test
cargo ci-clippy

Runtime sprites

Runtime sprites are checked in under assets/pixel-sprites/. Treat them as release assets unless a dedicated sprite workflow is added back to the project.

Screenshot refresh

Run this after UI, layout, theme, sprite-fit, visual-effect, or renderer changes:

scripts/update-readme-screenshots.sh

The script renders fresh README images into docs/screenshots/ and refreshes the marked screenshot sections in this file.

Website build

The standalone site lives in website/. Build the Cloudflare Pages output locally with:

scripts/build-website.sh
node scripts/test-website.mjs

The install button copies:

curl -fsSL https://i.tui-alchemy.sh | sh

For Cloudflare Pages, custom domains, R2 provisioning, and one-time DNS setup, copy .env.example to .env, fill the tokens, then run:

scripts/deploy-website.sh
node scripts/configure-cloudflare-dns.mjs

Pushes to master run the same website build and deploy path through .github/workflows/deploy-website.yml.

Package check

Before a release, verify crate metadata and included files:

cargo package --list
cargo package

Release checklist

1. Update version in Cargo.toml.
2. Add a matching entry to CHANGELOG.md.
3. Regenerate README screenshots with scripts/update-readme-screenshots.sh.
4. Build and test the website with scripts/build-website.sh and node scripts/test-website.mjs.
5. Review the updated images in docs/screenshots/.
6. Run cargo test.
7. Run cargo ci-clippy.
8. Run cargo package.
9. Commit the release changes.
10. Tag the release commit, push it, and create the GitHub release from docs/release-v0.2.0.md.

License

MIT. See LICENSE.