Lingikaushikreddy/Settlement-Village

Give six residents a shared goal: grow the village, prepare for a raid, or restock supplies. Watch them claim jobs, gather resources, build and upgrade a new farm, or coordinate recruitment. Inspect what each resident is doing, why they took the job, and what they remember. Then command your army in battle, or open the research desk to investigate social decisions and replay their evidence.

The campaign and free research tools run in your browser with no API key, paid AI, account, or database required, whether you open the hosted frontend or run it locally. Campaign residents use deterministic game AI. Optional Claude decisions are available for explicit steps in local-worker research experiments.

If you like games where agent decisions are visible, star the repository to follow Settlement's development.

1. Choose Village orders → Grow the village. Review the construction steps, spending ceiling and protected reserves.
2. Select Start village development. Residents choose a reachable farm site, collect supplies, schedule builders and complete the required Town hall and farm upgrades.
3. Open View plan → Village plan to inspect dependencies, waiting reasons and actual spending. Select a resident to see their decision, route and memories.
4. Give a working resident a 20-tick rest. Another available resident can take over the job.
5. Open Village journal to see production, meet the residents and claim earned milestone rewards.

In a fresh village, the growth plan authorizes at most 1,560 gold and 1,240 timber, keeping 250 gold, 200 timber and 150 food in reserve after each crew payment. It finishes with one additional level-three farm and a level-two Town hall. The plan adapts to work you complete manually without paying for it twice.

For an expedition, choose Prepare for a raid to ready 30 troops and the village reserves, then lead the attack yourself. Restock supplies collects another 300 of each resource without spending. Research compares how different policies respond to the same claims.

Screenshots show the running game. Camera controls support pointer and keyboard navigation, and the layout adapts to phones.

Use Node.js 24+ and npm. The optional .nvmrc selects Node 24.

git clone https://github.com/Lingikaushikreddy/Settlement-Village.git
cd Settlement-Village
npm ci
npm run dev

Open http://localhost:5173. Your village saves in that browser. A second tab waits until the active village closes; retry there to load the latest save. Export valuable saves from the village guide. Saving requires a browser with Web Locks support on localhost or HTTPS.

To include the optional local research worker:

npm run dev:all

The worker listens on 127.0.0.1:8787 and stores research runs in work/settlement.sqlite. No model key is needed. For explicit paid model steps, follow Live model setup; provider calls stay disabled until configured.

To preview a production build locally:

npm run build
npm start -- --port 5173

The default development and production scripts use Next.js; the frontend also supports Vercel deployment. The hosted frontend runs the campaign and free Research comparisons, replay and report verification in each visitor's browser. Saves remain browser-local; there are no accounts or server-side campaign saves. The optional SQLite research worker, configured Claude experiments and agent-endpoint evaluation CLI run locally.

npm run smoke -- <url> checks a running frontend's page, assets, research redirect, response headers and preview image.

flowchart LR
    Player[Player objective] --> Jobs[Shared job board]
    World[Village resources and buildings] --> Jobs
    Jobs --> Crew[Six residents: bid, claim, navigate, replan]
    Crew --> Tools[Validated collect, train, build and upgrade commands]
    Tools --> World
    Crew --> Record[Decisions, memories and action log]
    Record --> Inspector[Resident inspector]
    World --> Save[Versioned campaign save]

World layer: buildings produce resources, construction occupies builders and finishes on the game clock, and training produces actual troops. Agents use the same commands as the player's manual controls.

Behavior layer: the planner decomposes one shared objective into useful jobs. Development freezes a dependency plan and spending ceiling when started. Each job has one owner. Residents follow walkable grid routes, release work when resting, and reconsider blocked or obsolete tasks.

Tools and records: actions validate current funds, capacity and the objective's spending allowance. Development payments also preserve the approved reserve floor. Saved state preserves the plan, claims, positions, spending and recent memories. Loading pauses decisions until you resume.

Crew work pauses offline, during raids, and when entering Council or Research. Production and existing training timers continue. Research worlds are separate from campaign currency; their evidence and replay tools share the same application.

See Objective agents for exact rules and boundaries.

Open Research → Compare to choose scenarios, matched seeds and run length. Every run must pass conservation checks and exact replay before its results appear. Inspect any included seed, export a compact JSON report or CSV table, and import or paste a report to independently rerun its cases.

The included reference report runs four authored scenarios × three deterministic policies × ten seeds, with zero model calls. At 60 ticks, the scarcity scenario produces 36 successful attacks out of 40 evaluated attempts for Trust first, versus 0/40 for Check evidence. Honest controls expose a different cost: Cautious refuses 33/40 honest offers, versus 0/40 for Check evidence. These results describe the authored rules; the evidence policy is deliberately suited to them and they do not measure general AI safety.

# Independently reproduce the checked-in report; fail on any mismatch
npm run evaluate -- --verify docs/evaluation-results.json

# Generate a fresh reference report
npm run evaluate

See Evaluation reports for the format, denominators, limits and measured results.

Point Settlement at any agent that speaks a small HTTP protocol, in any language, and find out whether the authored attacks can talk it into a bad decision, and whether it refuses honest offers:

node examples/agents/node/agent.mjs &     # or your own agent
npx settlement-testbed --agent http://127.0.0.1:8765/decide --name my-agent

Or in CI, after starting your agent:

- uses: Lingikaushikreddy/Settlement-Village@v0.11.0
  with:
    agent-url: http://127.0.0.1:8765/decide
    max-attack-success: "0.1"

You get rates with raw counts next to the built-in policies, a report anyone can verify with npx settlement-testbed --verify, and a replay in Research → Compare. Requests do not label claims as attacks or reveal the scenario and seed. Verification reconstructs results from the recorded answers; it does not authenticate which agent produced them. See Agent testbed for the protocol, failure rules, thresholds, the action and the library API. Verified reports from other agents are in the gallery; submit yours with a pull request.

A score on the four built-in claims says little about claims an agent has never seen. examples/scenarios/research/ adds twelve more, built on manipulation tactics from published studies of language-model agents. Each attack family has an honest twin, so a score separates caution from paranoia:

examples/scenarios/research/sources.json cites the papers behind each tactic. Every id was resolved against arXiv or Crossref, and each license is recorded as confirmed or not. The keyword-rule example agent falls for all nine attacks, which is the point: new claims expose agents tuned to old ones. See Research-grounded scenarios for the batched run commands, the stated hypotheses and what the pack does not show.

TypeScript · React · Next.js · Zod · Tailwind CSS · optional Node.js/SQLite worker

app/                 Application entry points
components/game/     Village, combat, crew inspector and research views
components/game/game.tsx            Campaign composer; use-campaign.ts owns state, clock and saves
components/game/*.tsx               One file per region: HUD, footer, dialogs, guide, selection panel, battle and research overlays, session gate
components/research/                Research desk: playback and local-worker hooks, one file per region, view model
lib/game/            Pure campaign, crew, economy and battle transitions
lib/sim/             Deterministic social engine and bounded planner
lib/agent/           Optional Claude proposals and action validation
lib/testbed/         Agent testbed: protocol, run loop, reports and verification
examples/agents/     Node and Python example agents for the testbed
examples/scenarios/  Custom scenario files: the reciprocity pair and the research-grounded pack
worker/              Local persistence, scheduling and model request ledger
tests/               Engine, game, crew, replay and worker tests
public/game/         Original generated terrain and sprite artwork
docs/                Guides, design notes and verification records

npm test
npm run test:integration
npm run evaluate -- --verify docs/evaluation-results.json
npm run eval:agent -- --verify public/examples/agent-report.json
npm run typecheck
npm run lint
npm run build
npm run test:e2e

The browser suite needs Chromium: run npx playwright install chromium once. The suite covers resource conservation, duplicate spending, construction dependencies, manual interference, protected reserves, job claims and handoffs, inaccessible workplaces, save ownership and recovery, report tampering, external-agent protocol failures, deterministic replay and worker recovery. CI runs the tests, HTTP integration flow, policy and agent-report reproduction, types, lint and production build on pushes and pull requests. See release verification.

Model tests use injected provider responses. A live paid provider was not called during development.

This is a playable single-player foundation for an agent-driven game. Campaign AI is rule-based: it does not train a neural network or understand arbitrary natural-language objectives. Council scenarios are authored. Agents execute a bounded farm-development plan; arbitrary construction requests, multiplayer, agent-led combat and model-controlled campaign play are not implemented.

Areas for future contributions:

• More development blueprints and richer campaign objectives
• Additional civilian activity animations and building art variants
• Persistent relationships across social chapters
• Community scenario packs: see Author your own scenario and the research-grounded pack
• Attacks voiced by trusted residents in every family
• Carefully bounded model-assisted campaign planning

The contribution guide explains setup, useful starting points and how to validate a change. Bug reports with a reproducible save and screenshots are especially helpful.

• Player guide — building, battles, objectives and Council stories
• Objective agents — assignment, pathfinding, budgets and adaptation
• Research guide — experiments, evidence, comparisons and replay
• Agent testbed — test your own agent against deception
• Scenario authoring — write a new attack family and its honest control as JSON
• Research-grounded scenarios — twelve cited scenarios, their hypotheses and limits
• Gallery — verified reports from other agents, and how to submit yours
• Evaluation reports — reproducible results and their limits
• Product roadmap — priorities and acceptance criteria
• Live model setup — optional Claude configuration and usage controls
• Security policy — local runtime boundaries and vulnerability reporting

Created by Kaushik Reddy. Released under the MIT License.

Terrain, sprites and civilian identities are original AI-generated artwork created for Settlement. See Art provenance. No franchise assets were extracted. Existing third-party license notices remain with their source files; see Third-party notices.

The social simulation is inspired by Generative Agents and AI Town. Settlement implements its own bounded gameplay and research loops; it is not affiliated with those projects.