Terminal Survival

Terminal Survival is a TUI-based roguelike game about staying alive in a procedurally generated wasteland. You scavenge, manage hunger and thirst, fight or avoid hostile encounters, and push farther from the starting point before the run falls apart.

Contents

• Quick Start
• World And Survival
• Combat
• Inventory And Equipment
• Items And Loot
• NPCs
• Commands
• Saving
• Development
• Troubleshooting
• Credits
• Patch Notes

Quick Start

python run.py

World And Survival

The world is a coordinate grid. You start at (0, 0) and move north, south, east, or west. Locations are generated from the save seed, then kept in the save file so returning to a place shows the same terrain, items, enemies, and NPCs.

Movement advances turns, drains hunger and thirst, and can trigger random events. Hunger and thirst start at 100. If either reaches zero, your health starts dropping until you recover or die.

Some tiles are blocked by rivers, cliffs, or rubble. Failed movement reveals the obstacle and remembers it on the map.

Combat

Combat is turn-based. You attack first, then any surviving enemy can strike back. Weapons use accuracy, damage ranges, ammo rules, and durability. Armor reduces incoming damage and wears down as it protects you.

Low hunger, low thirst, darkness, and heavy inventory can make fighting harder. If an enemy spots you, moving away requires a flee roll and can give the enemy a free attack.

Human enemies can carry weapons, ammo, armor, and sometimes night vision. Defeating them can leave that gear behind.

Inventory And Equipment

Inventory is limited by weight. Over 30kg starts to hurt combat accuracy, over 45kg hurts more, and at 60kg you cannot pick up more.

You can equip one weapon and one armor item. Special gear such as night vision goggles and binoculars can be carried or equipped depending on the item behavior, and durable items show their remaining condition in the item name.

Items And Loot

New runs start with a Glock 17, pistol ammo, a combat knife, a bandage, and water.

Loot includes weapons, ammo, armor, medicine, food, drinks, money, scrap, and special equipment. Rarity tiers are common, uncommon, rare, and very rare. Weapons found as loot often spawn with compatible ammo nearby.

Special items:

• Trap disarm kit: protects against traps until its durability runs out.
• Night vision goggles: reduce darkness penalties.
• Binoculars: improve directional looking and can reveal enemies nearby.

NPCs

Friendly NPCs can appear in locations:

• Talkers share flavor text.
• Quest givers provide quest hooks.
• Traders buy and sell goods.
• Repairmen restore damaged weapons and armor for scrap and dollars.

Use interact, talk, trade, buy, sell, or repair depending on context.

Commands

go <direction>        Move north/south/east/west
look <direction>      Check an adjacent tile
map, m                Open the map

take <item>           Pick up an item
take all              Pick up everything possible
drop <item>           Drop an item
drop ammo             Drop all ammo
drop weapons          Drop all weapons
drop misc             Drop junk items
equip <item>          Equip weapon, armor, or supported special gear
use <item>            Use a consumable or supported special item
inspect <item>        Show item details
inspect weapons       Compare carried weapons

attack <enemy>        Attack an enemy
bribe                 Attempt to bribe a human enemy
interact              Talk, trade, repair, or bribe based on context

leaderboard, lb       Show run records
save, s               Save the run
delete_save, ds       Delete the save file
quit, q               Quit after confirmation
help, h               Show help

Saving

Saving is manual with save. Source runs store saves under data/; packaged runs use the user data location. Game over deletes the active save and records the run on the leaderboard.

Development

Install dependencies:

pip install -r requirements.txt

Run the game:

python run.py

Run tests on Windows:

set PYTHONPATH=.
python tests/runtime_tests.py
python -m unittest discover -s tests

Run tests on Unix shells:

PYTHONPATH=.
python tests/runtime_tests.py
python -m unittest discover -s tests

Internal references:

• INTERNAL_GAME_API.md covers the UI-agnostic game API.
• ADMIN_COMMANDS.md lists development/admin commands.
• Set TS_ADMIN_MODE=1 to enable admin commands during local testing.

tests/manual_test_screens.py is a manual, non-automated screen check.

Troubleshooting

python run.py starts the Textual UI. If a packaged executable exits unexpectedly, check for terminal_survival_crash.log near the executable or in your home directory.

Credits

Developed by Luca "Syr" Lombardo. Some content, including descriptions and flavor text, was drafted with AI tools.

Patch Notes

Alpha 0.4 (TBR)

• Added NPC encounters: talkers, quest givers, traders, and repairmen.
• Added the unified interact command and context-aware UI button.
• Added a scrollable map with NPC markers.
• Added trap disarm kits, night vision goggles, and binoculars.
• Added quit confirmation.
• Added admin commands for development testing.
• Improved inventory panels, money display, ammo display, and item selection.
• Fixed hidden-looting detection, spotted drop turn costs, turn counter display, equipped item highlighting, special item use/equip shortcuts, and wrapped item click handling.

Alpha 0.3 (2026-01-22)

• Added bribery, directional look, enemy inspection, multi-item take/drop, and category drops.
• Human enemies can use and drop gear.
• Rebalanced weapons, armor, loot rarity, ammo quantities, critical hits, and boss spawning.
• Added a turn counter and improved inventory/map display.

Alpha 0.2 (2025-12-31)

• Added durability penalties for weapons and armor.
• Added drop item xN.
• Tuned shotgun and weapon prices.
• Expanded map and character UI.
• Added save deletion on game over.

Alpha 0.1 (2025-12-28)

• Initial release.