Arx II

Arx II is the sequel to Arx: After the Reckoning, built on the Evennia framework.

Sandboxed devcontainer (recommended for Claude Code)

Run Claude Code with --dangerously-skip-permissions safely inside a Docker container with an egress firewall. The container is the filesystem boundary; the firewall is the network boundary. Bootstrap the host once with .\scripts\bootstrap-devcontainer-host.ps1 (PowerShell; see the guide if execution policy blocks it), then just dc-up to start the stack and just dc-shell to get a shell inside it.

See docs/devcontainer-setup.md for the full guide.

Development Setup (Windows)

This project uses mise to manage runtime versions and uv to manage Python dependencies.

Prerequisites

• Git ≥ 2.29
• mise
• PowerShell 7+ (Windows PowerShell 5.1 is not supported for shell hooks)

Note: Python 3.13 will be automatically installed by mise.

Install mise using winget in PowerShell 7+:

winget install jdx.mise

⚠️ Ensure Python, Git, and mise are in your system PATH. After installing mise, you may need to restart your terminal.

PowerShell 7+ Setup

1. Install PowerShell 7+

   • Download the latest version from: PowerShell GitHub Releases
   • Or install using winget:

     winget install --id Microsoft.PowerShell --source winget

2. Set as Default Shell (Recommended)

   • Open Windows Terminal
   • Click the down arrow next to the tab and select "Settings"
   • Under "Startup > Default Profile", select "PowerShell"
   • Click "Save"

Installation

Open PowerShell and run the following commands:

Clone the repository

git clone https://github.com/Arx-Game/arxii.git
cd arxii

Set up development environment

1. First, trust the project's configuration (you'll be prompted to confirm):

mise trust

2. Install the required tools:

mise install

Making mise available in your terminal

3. Set up mise to be available in all terminal sessions by adding it to your PowerShell profile. First, ensure the profile directory exists and create it if needed:

# Create the PowerShell profile directory if it doesn't exist
if (-not (Test-Path -Path "$HOME\Documents\PowerShell")) {
    New-Item -ItemType Directory -Path "$HOME\Documents\PowerShell" -Force
}

# Add mise activation to your PowerShell profile (with proper newline)
Add-Content -Path $PROFILE -Value "`nmise activate pwsh | Out-String | Invoke-Expression"
# Note: The backtick before 'n ensures this starts on a new line in your profile

4. Close and reopen your terminal for the changes to take effect. The next time you open PowerShell, mise will be automatically activated.

5. In your new terminal session, verify the installations:

node --version  # Should show v20.0.0
python --version  # Should show Python 3.13.x
uv --version  # Should show the installed version

Note: If you don't want to restart your current terminal, you can manually activate mise in your current session with:

mise activate pwsh | Out-String | Invoke-Expression

Set up the virtual environment and install dependencies

uv venv
uv sync

Verify installations

Check that the correct versions are being used:

python --version  # Should show Python 3.13.x
node --version   # Should show v20.x.x
npm --version    # Should show 11.5.1

Create an empty .env file inside the src directory

New-Item -Path .\src\.env -ItemType File

Install pre-commit hooks

pre-commit install

First-run seeding

After uv sync and arx manage migrate, populate sane defaults:

arx seed dev

Idempotent — safe to re-run; it only fills missing rows and never overwrites your edits or loaded fixtures. Superusers can also click Load sane defaults in Django admin.

The Big Button's post-seed redirect lands on the Game Setup hub (/admin/_game_setup/), a superuser-only landing page laying out the clone→seed→tweak→export flow with a live per-cluster content inventory. From there, Game Tuning (/admin/_tuning/) offers check/consequence/condition difficulty analytics and a Monte Carlo party-vs-boss simulation preview, and Game Ops (/admin/_ops/) surfaces progression/economy/story/reports analytics plus a technical-health snapshot. If you maintain a private content repository, set CONTENT_REPO_PATH in src/.env and the hub also offers an optional Load content repo step to build and upsert it into the database.

Using the arx CLI

After setup, use the arx command-line tool:

Run tests:

arx test

Run tests with coverage:

arx test --coverage

Launch a Django shell:

arx shell

List URL routes:

arx manage show_urls

Build the frontend:

arx build

Start the server:

arx start

Build frontend and start server:

arx serve

This command compiles the React app, collects static files, and launches the Evennia server.

Stop the server

arx stop

Reload running server code

arx reload