Home

High-level roadmap

Vision: Single-player, modular, data-driven text adventure engine in C with scripting/data files for rooms, items, NPCs, puzzles, save/load, CLI UI, extensible content format, and automated testing/CI.
Target platforms: Linux (primary), macOS, Windows (via MSYS/MinGW or WSL).
Release stages: Prototype → Alpha (playable demo) → Beta (polished content + testers) → 1.0 (public release).

Epics (big chunks)

Project Foundation & DevOps
Core Engine (I/O, parser, world model)
Game Systems (items, inventory, puzzles, NPCs)
Content Pipeline & Tools (data format, editor, import)
UI & UX (console experience, accessibility)
Testing & Quality (unit tests, integration, fuzz)
Release Packaging & Distribution
Community & Docs (player manual, modding guide)

For each epic below I give Features → Example User Stories → Concrete Tasks and Acceptance Criteria.

Epic 1 — Project Foundation & DevOps

Features:
    Repo layout and coding standards
    Branching strategy and PR policy
    Azure DevOps: Boards, Repos, Pipelines, Artifacts
    Project templates and issue templates
Example user story: As a developer, I want the repo to have a clear structure and CI so code builds and tests run automatically.
    Tasks:
        Create repository skeleton (src/, include/, data/, tests/, tools/, docs/, examples/, Makefile).
        Add CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE, README.md.
        Set up clang-format and style guide; commit pre-commit hook instructions.
        Define branching strategy (main = protected release branch; develop for daily; feature/, hotfix/).
        Create PR template and issue templates (bug, feature, story).
        Create Azure DevOps project and import repo (or connect).
    Acceptance criteria:
        Repo builds on dev machine with make.
        PR template present; main protected by branch policy requiring 1+ approver + successful pipeline.
        Board created with sample backlog.

Epic 2 — Core Engine

Features:
    Robust command parser (verb-object, prepositions)
    World model: rooms, exits, items, entities
    Game loop and event dispatch
Example story: As a player, I can type commands like "take lamp" and the engine will update state and show results.
    Tasks:
        Design data model structs (Room, Item, Player, World, Entity).
        Implement core loop: read command → parse → execute → render.
        Implement tokenizer and grammar: verbs, nouns, adjectives, prepositions; synonyms support.
        Implement command dispatch table and handler interface.
        Add debug logging and a developer console mode.
    Acceptance criteria:
        Engine can load minimal world file and respond to "look", "inventory", "go north".
        Parser recognizes basic predicates and returns parse tree for handlers.

Epic 3 — Game Systems

Features:
    Inventory, item interactions, containers
    Puzzle system and stateful triggers
    NPCs with simple behaviors/dialogue
    Save/load (versioned)
    Events & scripting hooks
Example story: As a player, I can pick up items, combine them, and solve a locked-door puzzle.
    Tasks:
        Implement Item and Inventory API with constraints (weight, capacity).
        Implement Lock/Key mechanic and puzzle triggers.
        Design event system and simple scripting hook interface (C callbacks or embedded minimal script DSL).
        Implement save/load (binary or JSON/TOML) with version header.
    Acceptance criteria:
        Save files load to the same game state.
        At least one multi-step puzzle implemented and testable.

Epic 4 — Content Pipeline & Tools

Features:
    Data format for rooms/items/NPCs (JSON/TOML/YAML or custom)
    Tool to validate data and compile to binary if desired
    Example content set for demo
Example story: As a content author, I want to write room data in a human-readable format and validate it.
    Tasks:
        Decide data format (recommend: JSON or TOML for ease; consider Lua if scripting).
        Implement loader/validator and schema checks (required fields, type checks).
        Create a small "starter adventure" dataset.
        Add a "world compiler" tool that preloads and checks asset references.
    Acceptance criteria:
        Content validator reports errors/warnings.
        Engine can load authored content at runtime.

Epic 5 — UI & UX

Features:
    Command line interface with history & simple auto-complete
    Clear rendering of room descriptions, inventory, examination
    Accessibility features (high-contrast, screen-reader friendly text)
Example story: As a player, I can press Up to recall previous commands and Tab to autocomplete verbs.
    Tasks:
        Add line editing: use linenoise/readline integration.
        Add pager for long descriptions; word-wrap.
        Implement config file for colors and accessibility settings.
    Acceptance criteria:
        CLI supports command history and simple completion for verbs and item names.

Epic 6 — Testing & Quality

Features:
    Unit tests for parser, serialization, game logic
    Integration tests: scripted playthroughs
    Static analysis and sanitizers
Example story: As a developer, I want automated tests and pipelines so breaks are caught early.
    Tasks:
        Choose C test framework (Unity, CMocka, or MinUnit).
        Write unit tests for parsing and core API.
        Create integration harness to run sample command scripts and assert outputs.
        Add CI steps: run make, run tests, run clang-tidy, run ASAN/UBSAN builds (when possible).
        Add coverage collection (gcov/lcov) and report generation.
    Acceptance criteria:
        CI pipeline runs on PRs and reports pass/fail.
        Minimum test coverage threshold (e.g., 60%) for core engine.

Epic 7 — Release Packaging & Distribution

Features:
    Build artifacts for target platforms
    Installer or tarball release with license and docs
    Versioning and changelog
Example story: As a user, I can download a tar.gz with the binaries and example content.
    Tasks:
        Add Makefile targets for release builds and packaging.
        Create a release pipeline that builds on tags and publishes artifacts.
        Add semantic versioning and CHANGELOG.md guidelines.
    Acceptance criteria:
        Release artifacts are published automatically on tag + PR merge.

Epic 8 — Community & Docs

Features:
    Player manual, modding guide, developer docs
    Examples and tutorials
Example story: As a modder, I can read the modding guide and create a new room and NPC.
    Tasks:
        Write README with build/run instructions.
        Author docs/architecture.md that explains core design.
        Create docs/content-format.md describing data schema and examples.
    Acceptance criteria:
        New contributor can get dev env running and load example world in ≤30 minutes.

MVP (prioritized minimum viable product)

Core loop + basic parser.
Rooms, exits, 'look', 'inventory', 'go' commands.
Items: take, drop, examine.
Save/load.
Small example map with 6–10 rooms and a simple puzzle.
Basic Makefile and CI pipeline that builds and runs unit tests.

Development process and Azure DevOps specifics

Project setup:
    Create Azure DevOps project (name: text-adventure).
    Create repos or import GitHub repo into Azure Repos (or keep GitHub and integrate with Azure Pipelines).
    Set up Boards: create Epics → Features → User Stories.
    Create iterations (e.g., Iteration 1..6, each 2 weeks).
Branching & policies:
    Branches: main (protected), develop, feature/<ticket-id>-short-desc.
    PR policy: require 1+ reviewer, passing CI, no merge conflicts.
    Enforce signed commits or conventional commit messages (optional).
Pipelines:
    CI pipeline triggered on PRs and commits to develop/main.
    Tasks: checkout, install dependencies, build (make), run unit tests, run static analyzer, generate test/coverage reports, upload artifacts.
    CD pipeline (optional): when creating releases or tagging, build release artifacts and publish to GitHub Releases/Azure Artifacts.
Work item templates:
    Provide templates for Bug, Feature, User Story with fields: Title, Description, Acceptance Criteria, Estimate (story points), Priority, Tags, Area, Iteration.
Estimation and velocity:
    Use story points or time estimates. Typical sprint is 2 weeks.
    Start with small, vertical slices (each story should deliver a testable piece of functionality).
Definition of Done (DoD) — apply to user stories and PRs:
    Code builds and tests pass in CI.
    Unit/integration tests added for new logic.
    Documentation updated (if API/behavior changed).
    Code reviewed and approved.
    No high-severity lint/static analysis issues.
    Manual smoke test passed (developer verified).

CI/CD checklist (concrete)

CI tasks:
    Build in debug mode (with -g), run unit tests.
    Build in release mode and run static analyzer.
    Optional: ASAN/UBSAN build on a scheduled pipeline.
    Run data validation for content files (schema check).
    Generate artifacts on successful main merge.
Tooling suggestions:
    Build: gcc/clang + Makefile.
    Static analysis: clang-tidy, cppcheck.
    Formatting: clang-format.
    Tests: Unity, CMocka, or your preferred C testing framework.
    Coverage: gcov + lcov.
    Memory/debug: ASAN, UBSAN, Valgrind locally.
    Fuzzing: libFuzzer or AFL for parser inputs (advanced).
Pipeline YAML example (conceptual steps to add to Azure Pipelines):
    checkout
    make deps / prepare (install test runner)
    make all
    make test
    run clang-tidy; fail on critical warnings
    collect and publish test results and coverage
    on main: package artifacts and publish release

Testing strategy (concrete)

Unit tests for:
    Parser/tokenizer edge cases.
    Serialization/deserialization (save/load).
    Inventory and item behaviors.
Integration tests:
    Scripted playthroughs: feed a sequence of commands and assert printed output/state.
Fuzz tests:
    Feed random inputs to parser to find crashes.
Regression tests:
    Add tests for bugs as they are found.
Test data:
    Provide test fixture worlds with controlled scenarios.

Data format & content design

Use a human-editable format: JSON/TOML/YAML for static content. Consider Lua for scripting.
Keep content data-driven: avoid hardcoding puzzles in C.
Version content files and include version header in save files.
Example data model fields:
    Room: id, name, short_desc, long_desc, exits[], flags, scripts.
    Item: id, name, description, weight, properties (takeable, readable), on_use script.
    NPC: id, name, dialogue, inventory, behavior_script.
    Trigger: event, conditions, actions.

Developer ergonomics & contributor experience

Provide clear README: build/run/test examples.
Add sample world and “play” script.
Add tests and a CONTRIBUTING guide with PR checklist.
Create small starter issues for newcomers (good first issue).

Quality & UX polish (post-MVP)

Spell-check of in-game text.
Tone/style guide for narrative voice.
Localization-ready strings file.
Add audio/visual hooks (if later adding GUI).
Accessibility: screen-reader friendly output format and options to slow text.

Security & maintenance

Validate all external input (parser).
Handle malformed save files gracefully.
Consider sandboxing any scripting engine.

Templates & examples (use these to create Azure Boards items)

User Story template:
    Title: [Feature] Short description
    Description: As a <role>, I want <goal> so that <benefit>.
    Acceptance criteria:
        AC1: ...
        AC2: ...
    Estimate: X points
    Tasks: list (small concrete tasks)
PR template:
    Summary of change
    Linked work item IDs
    How to test locally
    Checklist: build/tests pass, docs updated, reviewer assigned

Prioritized next steps (concrete)

Decide MVP scope (recommend core engine + basic parser + inventory + save/load + small world).
Create Azure DevOps project and a Board with the Epics above.
Create repo scaffold (src/, include/, data/, tests/, docs/, Makefile) and push it.
Create initial CI pipeline that runs make and unit tests.
Open first stories (parser, core loop, simple world) and start a 2-week sprint.
Implement and iterate: after you have the engine responding, add content and puzzles.

Quick checklist summary you can copy into Azure Board or a spreadsheet

Setup & repo
    Create repository skeleton + README/CONTRIBUTING/LICENSE
    Add coding style & pre-commit notes (clang-format)
    PR/issue templates
    Branch policies (protect main; require PR + CI)
CI & DevOps
    Azure Pipelines: build + test
    Static analysis + sanitizer builds (ASAN)
    Coverage reporting
    Release pipeline for tagged builds
Core engine
    Command loop & tokenizer
    Parser with basic grammar
    World model (Room/Item/Player)
    Command handlers: look, go, take, drop, examine, inventory
Game systems
    Inventory & item interactions
    Save/load
    One multi-step puzzle (lock & key)
    Event system
Content & tools
    Choose data format + loader
    Content validator tool
    Example world data
Testing & QA
    Unit tests for core modules
    Integration script tests (playthrough)
    Add at least one fuzz/ASAN job (optional)
Docs & community
    Player manual / quickstart
    Developer architecture document
    Modding guide / data schema
Release
    Release packaging (tar.gz)
    CHANGELOG + versioning policy