LevelKit-Text
A zero-dependency Python text adventure engine built for the classroom.
Overview
LevelKit-Text is a classroom-ready text adventure engine built in Python with Tkinter. It gives students a fully functional RPG framework with room navigation, turn-based combat, inventory, XP levelling, audio, and theming. Students build their own adventures by editing content files without touching engine code. The entire stack runs on Python's standard library, so there is nothing to install beyond Python itself.
Text-based games are one of the best entry points into programming for secondary students. They combine creative writing with logical thinking, and students can see results immediately. The problem is that building one from scratch is too much scaffolding for most Year 8 to 10 classes. LevelKit-Text solves this by giving students a working engine and asking them to build the content.
The architecture separates engine code from student-editable content. The engine directory contains the game loop, combat system, UI renderer, save/load logic, audio, and a validation tool. Students never need to open those files. Instead, they work in clearly separated directories: defining rooms, battles, items, weapons, themes, and XP curves using Python dataclasses.
Adding a new room is as simple as creating a file in the levels directory following a naming convention. The loader auto-discovers it. No registration step, no imports to manage. This convention-based approach means students focus on game design decisions rather than plumbing code together.
The built-in validator is a teacher tool: run it before a student demo and it checks that all room transitions resolve, all battle references exist, all asset keys point to real files, and performs a depth-first reachability analysis to flag orphaned rooms. This catches broken games before they reach the classroom.
FEATURES.
Room Navigation System
Rooms defined as dataclasses with narrative text, background images, music, and branching options. Options can be gated by flags, expressions, or item prerequisites.
Turn-Based Combat
Battles with attack, cast, and skill check actions. Enemy entities with HP, attack, defence, and probabilistic loot tables. Distinct victory and defeat outcomes.
Inventory and Equipment
Dual-slot equipment system with stat effects. Items have categories, stackability, and effect dictionaries. Visual inventory sidebar with tooltips.
Flag and State System
Persistent boolean flags with timed expiry and nested expressions (all, any, min). Powers branching narratives and puzzle gating without students writing conditional code.
XP and Levelling
Configurable experience curve with explicit early thresholds and exponential growth factor. Teachers can adjust the curve to match learning objectives.
Full Theming Engine
A deeply nested theme dictionary controls every visual aspect: panel backgrounds with alpha, corner radii, fonts, button states, inventory styling, and layout proportions.
Content Validator
CLI tool that checks room transitions, battle references, asset keys, and performs reachability analysis. Catches broken games before playtime.
Cross-Platform Audio
Background music with looping and sound effects using only standard library modules. Graceful fallback if audio files are missing.
Tech Stack
Core language for the entire engine, using only standard library modules
Canvas-based UI framework with layered rendering and dynamic resizing
Typed data modelling for all nine core game entities
File-based save/load persistence for game state
Convention-based dynamic module importing for content discovery
Architecture
The project follows a strict engine/content separation. The engine directory contains six modules: core (game loop and UI), models (nine dataclasses), loader (dynamic content discovery), validator (graph reachability checks), save (JSON persistence), and audio (cross-platform playback).
Student content lives in three directories: game (configuration like defaults, items, weapons, themes, XP curves), levels (one Python file per room following a naming convention), and battle_loops (one file per encounter). The loader auto-discovers content by scanning these directories for files matching naming patterns.
The Tkinter UI uses a layered canvas approach with background images on the bottom layer, then positioned widget panels for header, dialogue, options, and inventory. Everything anchors to canvas edges and supports dynamic resizing.
Data Model
- •Stats dataclass tracks HP, mana, attack, defence, and level for both players and enemies
- •RoomSpec and OptionSpec define rooms with narrative text, images, music, and gated branching choices
- •BattleSpec, BattleAction, and BattleOutcome model encounters with attack, cast, and skill check actions
- •Item and Weapon dataclasses handle inventory with categories, stackability, effects, and equipment slots
- •Enemy dataclass includes stat blocks, loot tables with probability rolls, and unique item tracking
Challenges
- •Keeping the engine zero-dependency so it runs on any school-managed machine without pip installs
- •Making the content layer simple enough for Year 8 students while keeping the engine flexible enough for advanced customisation
- •Cross-platform audio using only standard library modules across Windows, macOS, and Linux
- •Designing a flag and condition system powerful enough for branching narratives but intuitive enough for students to use
- •Balancing the dataclass-driven architecture: structured enough to validate, flexible enough to extend
Outcomes
- •Complete RPG framework with room navigation, combat, inventory, levelling, and theming
- •Zero external dependencies: runs anywhere Python is installed
- •Convention-based content discovery removes the need for students to manage imports or registrations
- •Built-in validation tool gives teachers confidence before student demos
- •Students learn game design, data modelling, and Python dataclasses through creative content authoring