Public roadmap · Open contribution
Choose the next system to build.
StoneSiege's roadmap is a dependency map for contributors: what already exists, what is missing, which foundations come first, and how to turn one ambitious phase into a focused issue and pull request.
Before implementation
One issue. One owner. One focused change.
Roadmap entries are directions, not permission to build an entire phase alone. Every contribution begins with an overlap check and a public GitHub issue so people and AI agents do not unknowingly solve the same problem twice.
- 01Search first
Search open and closed issues, then active pull requests, using the feature's real keywords.
- 02Claim or coordinate
Read assignees, recent comments, and linked PRs. If work is active, coordinate there instead of duplicating it.
- 03Create only when needed
If no matching issue exists, open one focused issue with the problem, scope, acceptance criteria, and tradeoffs.
- 04Link the pull request
Use an issue-numbered branch and put
Closes #123orRefs #123in the PR description.
Continuous
Keep the alpha healthy
Protect the playable game while larger systems are designed. Player-blocking bugs, accessibility, saves, device coverage, and measured performance remain the first responsibility.
Nothing — this work stays active throughout every phase.
Release confidence
Complete representative browser, Android, iPhone, and iPad QA; fix campaign blockers and input or safe-area regressions.
Performance evidence
Measure CPU, memory, battery, load time, bundle size, pathfinding cost, and large-battle rendering before raising budgets.
Player experience
Improve onboarding, help, accessibility, difficulty evidence, interrupted-match recovery, and honest project status.
Focused places to start
- Reproduce and reduce one mobile input or safe-area defect.
- Add a deterministic regression test for a confirmed simulation bug.
- Build one repeatable low-end-device or battle-performance benchmark.
- Audit one campaign chapter for blockers, unclear objectives, and resume behavior.
Exit signal
Existing-game instability is low enough that regressions introduced by new terrain, AI, or scenario systems are easy to identify.
Foundation
World and scale
Turn basic obstacle tiles into a world system and prove that a much larger battlefield can run reliably before it is offered to players.
Phase 00 performance baselines and stable save/restore behavior.
Huge-map budget
Benchmark a 192×192 target across fog, minimap, rendering, memory, save size, pathfinding, and 600–1,500 entity workloads.
Terrain depth
Expand rivers into tributaries, mouths, deltas, varied fords, and real bridges; evolve cliffs into elevation levels and explicit ramps.
Maps and biomes
Create reusable Inland, Riverlands, Highlands, Coastal, and Islands definitions with connectivity and resource validation.
Fortifications
Replace the one-tile gate simplification with formation-sized gates and make wall segments, corners, towers, and gates join reliably.
Focused places to start
- Add a headless 192×192 map benchmark without exposing a new menu option.
- Produce a validator report for unreachable resources and objectives.
- Specify and test river crossing placement as a pure deterministic generator helper.
- Write the multi-tile gate footprint and path-update design before changing art.
Exit signal
A validated 192×192 land map with several fortified regions can be saved, restored, and played on supported mobile hardware without pathing deadlocks.
Foundation
Strategic scenario systems
Give authors reusable strategic concepts instead of forcing every large story through hand-counted ASCII maps and entity-destruction triggers.
Phase 01 map representation and connectivity rules.
Regions and provinces
Add named regions, province ownership, and capture rules for towns, forts, ports, and civic landmarks.
Richer triggers
Add deterministic variables, counters, flags, region conditions, optional objectives, diplomacy changes, and reusable trigger groups.
Authoring and validation
Create a visual or data-assisted map tool plus linting for sealed routes, invalid references, impossible victory states, and entity budgets.
Long-game continuity
Add multiple named local saves, checkpoints, migrations, and clearer recovery while keeping progress on-device.
Focused places to start
- Draft a typed region schema with loader validation and round-trip tests.
- Add one scenario-lint rule with an intentionally failing fixture.
- Prototype a region-entered condition without changing existing chapters.
- Design named-save metadata and migration rules around the current snapshot format.
Exit signal
A contributor can author and validate a large province-based scenario without modifying engine code or manually maintaining hundreds of map rows.
Foundation
Large-war and empire AI
Make an established empire behave like an organized state—not a normal opponent with inflated resources or hidden combat bonuses.
Phase 02 provinces, strategic targets, and scenario controls.
Multi-base planning
Teach bots to operate several economies, rebuild selectively, and understand regional resource and production capacity.
Territorial defense
Give regions garrisons, reserve armies, rally routes, repair priorities, and responses to lost crossings or frontier forts.
Empire director
Allocate reinforcement and strategic budgets across local controllers while preserving deterministic, fog-honest behavior.
Difficulty and proof
Scale planning quality and tempo rather than unit stats; sweep headless scenarios for deadlocks, runaway production, and restore divergence.
Focused places to start
- Add a failing multi-base AI test with two separated Town Centers.
- Define a deterministic regional threat score from fog-honest sightings.
- Test that an AI rebuilds one strategically important production building.
- Create a headless stalemate detector for an authored large-war fixture.
Exit signal
The empire can defend several provinces, reinforce a threatened frontier, rebuild intelligently, and finish matches without omniscience or path-budget collapse.
Major mode
Grand Conquests
Add handcrafted, asymmetric adventures beside Practice and Historical Campaigns. Each begins from an unusual strategic situation and supports several viable routes.
Phases 01–03: scale, provinces, authoring, saves, and empire AI.
Mode shell
Add a third top-level play path with its own adventure cards, progress, briefing, saves, difficulty, and completion rules.
The Occupied Realm
Start the player in Castle Age with one settlement while an empire controls roughly half the map through four to six provinces and a capital.
Strategic choices
Support neutral towns, supply raids, mine control, alliances, frontier assaults, and province losses that weaken real imperial capabilities.
Long-form pacing
Use staged objectives and clear return-from-save guidance; victory should end at the capital, not with one hidden villager hunt.
Focused places to start
- Write the mode and first-adventure design document with explicit non-goals.
- Add a flow-state test for entering and leaving a third play mode.
- Define adventure metadata separately from historical campaign chronology.
- Prototype one province-loss effect in a small test scenario before building the huge map.
Exit signal
One polished, land-only Grand Conquest remains fun across repeated playtests and several difficulties, including reliable pause, save, restore, and victory flow.
Content expansion
More Grand Conquests
Combine the proven land and naval systems into distinct strategic stories rather than repeating the occupied-realm structure with different names.
A successful Phase 04 land adventure and Phase 05 naval vertical slice.
The Island Crown
Overthrow a naval power across an archipelago through fleet control, transport, and port capture.
The River Kingdoms
Control bridges, fords, ports, and river trade while choosing which local rulers to support.
The Broken Marches
Defend and rebuild a frontier as a larger empire attacks through mountain passes.
The Great Migration
Begin without a permanent capital, move a population across the map, then claim and defend a homeland.
Focused places to start
- Write one one-page adventure pitch with historical-status and system dependencies.
- Build a small mechanic-proof scenario instead of a complete adventure.
- Research and cite one proposed historical setting, unit, ship, or fortification.
- Add a reusable adventure objective template with focused tests.
Exit signal
Each adventure has a distinct strategic identity, accurately labels its relationship to history, and reuses validated systems rather than adding one-off engine branches.
Deeper RTS
Core depth, identity, and creation
Deepen the RTS and the contributor ecosystem after the major foundations have earned their complexity through playtests.
Priorities here can move forward independently when a contribution is small, safe, and well evidenced.
Strategy
Add trade routes, carts and ships, tribute, strategic sites or relics, regicide, patrol/guard/waypoints, stances, and richer siege interactions.
Civilization identity
Build distinct architecture, core troop silhouettes and animations, naval rosters, tech asymmetry, and historically grounded audio.
Presentation and reach
Add music, biome ambience, cinematic polish, localization infrastructure, accessibility expansion, and representative device QA.
Creation and replay
Support validated scenario/mod packages, compatibility rules, a replay browser, statistics, and sharable deterministic replay files.
Focused places to start
- Add one missing tooltip, accessibility label, or reduced-motion improvement.
- Research and document one civilization art or audio brief with sources.
- Expose one deterministic replay metadata field in a pure tested model.
- Write a mod-package threat model before proposing import or execution code.
Exit signal
New depth remains understandable on mobile, civilization identity is visible in ordinary play, and creator workflows are deterministic, licensed, validated, and safe.
Later research
Fair multiplayer—only after the single-player foundation.
The deterministic simulation makes lockstep research possible, but a real service also needs reconnection, spectators, desync diagnosis, accounts, moderation, privacy, matchmaking, hosting, and a sustainable operating model. It must not delay the world, naval, AI, accessibility, or Grand Conquests roadmap.
Ready to coordinate?
Give one claimed issue to your coding agent.
Replace the task placeholder only after the issue and pull-request overlap checks are complete. The prompt carries the coordination, architecture, testing, provenance, and pull-request requirements into the agent's working context.
You are contributing to StoneSiege, an open-source historical RTS. Do not stop after setup: complete the task and prepare a focused pull request.
CONTRIBUTOR REQUIREMENT
The contributor needs a free GitHub account to coordinate the issue, publish a branch, and open a pull request. Before implementation, confirm that they have an account and are signed in where the issue and pull request will be created. If they do not have an account, limit work to read-only investigation and explain that they must create and sign in to an account before the contribution can begin. Never create an account, request a password, or invent credentials for them.
ISSUE-FIRST COORDINATION — REQUIRED BEFORE IMPLEMENTATION
Every code, campaign, art, audio, balance, test, or documentation contribution must have one GitHub issue before files are changed. The issue is the public coordination record.
1. Search open and closed issues for the same problem or idea:
gh issue list --repo Knorcedger/stonesiege --state all --search "<keywords>"
2. Search open pull requests for overlapping work:
gh pr list --repo Knorcedger/stonesiege --state open --search "<keywords>"
3. If a matching issue exists, inspect its assignees, recent comments, and linked pull requests. If someone is actively working on it, coordinate in that issue and do not start a duplicate implementation. If it is available, comment with your intended scope and ask to be assigned or assign yourself when permitted.
4. If no matching issue exists, create one before editing. Describe the player or contributor problem, the proposed focused scope, acceptance criteria, and important tradeoffs. Do not open a duplicate issue merely to satisfy this rule.
5. Record the issue number. Name the branch for it and make the pull request close or reference it. Investigation needed to write or evaluate the issue is allowed; implementation starts only after the issue exists and the overlap check is complete.
TASK
[Describe the bug, feature, campaign, artwork, animation, balance change, or documentation improvement here.]
WORKFLOW
1. If StoneSiege is not already checked out, run:
git clone https://github.com/Knorcedger/stonesiege.git
cd stonesiege
2. Read AGENTS.md, README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, docs/ARCHITECTURE.md, and the documentation relevant to the task. Follow every nested AGENTS.md file that applies to files you touch.
3. Inspect git status before editing. Preserve existing work; never reset, overwrite, or discard changes you did not create.
4. Use Node.js 22.12+ or 24+, then install and run the project:
npm ci
npm run dev
Verify the game at http://localhost:5199.
5. Work on a dedicated branch unless the user already prepared one:
git switch -c contrib/<issue-number>-<short-description>
Never commit directly to main.
6. Implement only the requested change. Keep simulation code deterministic, keep presentation out of packages/sim, avoid unnecessary dependencies, and follow the existing architecture and visual language. New or AI-assisted assets must include provenance and licence information required by CONTRIBUTING.md and ASSET_LICENSE.md.
7. Add or update focused tests. For visible changes, capture before/after screenshots or a short recording.
8. Run the complete quality gate and fix failures caused by the change:
npm run check
9. Review the diff for correctness, secrets, unrelated formatting, accidental generated files, and undocumented asset provenance.
10. Commit with the Developer Certificate of Origin sign-off:
git commit -s -m "<imperative summary>"
11. Publish the branch to a Git remote you can write to and open a pull request against Knorcedger/stonesiege:main. Put “Closes #<issue-number>” in the pull-request description, or “Refs #<issue-number>” when the PR deliberately delivers only part of the accepted issue. Never push directly to main. If GitHub authentication or write access is unavailable, do not invent credentials—leave the branch ready and give the owner the exact commands needed to publish it and open the PR.
12. The pull-request description must cover the problem, solution and tradeoffs, tests performed, visual evidence when relevant, material AI assistance, and asset provenance or licensing considerations.
Return a concise summary with the changed files, verification results, commit, and pull-request URL (or the exact remaining publication commands).Canonical project record
Roadmap decisions live with the source.
The website explains the plan for potential contributors. The repository roadmap and issue history remain the canonical records for implementation status and accepted scope.