Development Setup

This guide helps you set up a complete local development environment for Areloria WASD.

Prerequisites

Ensure you have the following installed:

Requirement	Version	Purpose
Node.js	22.x+	Server runtime
pnpm	9.x+	Package manager
Python	3.x	Asset pipeline scripts
Docker	Latest	Container testing
Git	Any	Version control

Installation

1. Clone the Repository

git clone https://github.com/OuroborosCollective/Areloria-WASD.git
cd Areloria-WASD

2. Install Dependencies

pnpm install

3. Build Shared Package

The @wasd/shared package is required for both server and client:

pnpm -C packages/shared build

If you encounter import errors:

rm packages/shared/*.tsbuildinfo
pnpm -C packages/shared build

Project Structure

Areloria-WASD/
├── apps/                    # Application surfaces
│   ├── client-2d/          # 2D PixiJS + React client
│   ├── web/                # Web application
│   └── portal-replit/      # Replit portal
├── server/                  # Game server (Express + WebSocket)
│   └── src/
│       ├── core/           # WorldTick, systems
│       ├── networking/     # WebSocket server
│       ├── api/           # REST routes
│       └── game-data/     # Content JSON
├── packages/
│   └── shared/            # Shared types & utilities
├── docs/                   # Documentation
├── scripts/               # Build & utility scripts
└── .github/workflows/     # CI/CD

Running Development

Full Monorepo Build

pnpm build

Builds clients first, then the server with embedded Vite middleware.

Development Server (Recommended)

npx tsx server/src/index.ts

Server runs on port 3000 with Vite middleware for client assets.

Separate Client & Server

Terminal 1 - Server:

pnpm --filter @wasd/server dev

Terminal 2 - 2D Client:

pnpm --filter @wasd/client-2d dev

Environment Configuration

Create .env File

cp .env.example .env

Key Variables

Variable	Default	Description
`PORT`	`3000`	Server port
`NODE_ENV`	`development`	Environment
`PERSISTENCE_DRIVER`	`file`	Persistence mode
`AUTH_PROVIDER`	`none`	Auth provider

Development Auth

For development without authentication:

AUTH_PROVIDER=none
ALLOW_GUEST_LOGIN=true
ALLOW_DEV_LOGIN=true

Testing

Unit & Integration Tests

pnpm test

End-to-End Tests

# Install (first time)
pnpm run test:e2e:install

# Run
pnpm run test:e2e

CI Variant

pnpm run test:e2e:ci

Linting

pnpm lint

Runs ESLint across server and client code.

Building

Build Commands

Command	Description
`pnpm build`	Full monorepo build
`pnpm build:2d`	2D client only
`pnpm build:server`	Server only
`pnpm build:3d`	3D client only

Build Verification

pnpm run ci:verify

Runs lint, tests, and build without E2E.

Common Tasks

Adding a New System

Create system file in server/src/core/systems/
Register in TickSystemRegistry
Add to WorldTickScheduler
Write tests
Update documentation

Adding New Content

Content JSON files go in server/src/game-data/:

game-data/
├── npcs/
│   └── my-npc.json
├── items/
│   └── my-item.json
└── quests/
    └── my-quest.json

Asset Pipeline

Process Stitch-generated assets:

pnpm assets:stitch:intake
pnpm assets:stitch:validate

Troubleshooting

”Failed to resolve import @wasd/shared”

rm packages/shared/*.tsbuildinfo
pnpm -C packages/shared build

Port Already in Use

# Find and kill process on port 3000
lsof -i :3000
kill -9 <PID>

Client Shows Blank Page

pnpm build:2d
# Then restart server

Next Steps

Architecture Overview

Understand the system design

Quickstart

Quick start guide

Deployment

Deploy to production

Components

Documentation components

​Development Setup

​Prerequisites

​Installation

​1. Clone the Repository

​2. Install Dependencies

​3. Build Shared Package

​Project Structure

​Running Development

​Full Monorepo Build

​Development Server (Recommended)

​Separate Client & Server

​Environment Configuration

​Create .env File

​Key Variables

​Development Auth

​Testing

​Unit & Integration Tests

​End-to-End Tests

​CI Variant

​Linting

​Building

​Build Commands

​Build Verification

​Common Tasks

​Adding a New System

​Adding New Content

​Asset Pipeline

​Troubleshooting

​”Failed to resolve import @wasd/shared”

​Port Already in Use

​Client Shows Blank Page

​Next Steps