NodeUO

A modern Node.js Ultima Online shard, browser client, compatibility bridge, asset pipeline, and administration suite. NodeUO preserves the classic binary UO boundary while adding an independently negotiated JSON protocol for features shared only by the NodeUO server and client.

Current release: v1.0.0 · NodeUO JSON protocol package: 2.1.0

This repository does not include game files. You generate runtime assets locally from your own legal Ultima Online Classic installation.

Release 1.0

NodeUO 1.0 is the first tagged, end-to-end release of the complete workspace:

scripting, AI, combat, crafting, skills, magic, housing, boats, quests, vendors, death, ghosts, and world-generation workflows;

NodeUO interfaces, including visual-novel NPC interaction;

binary protocol and the TCP/WebSocket bridge;

enhanced engines and Classic UO gump fallbacks for the other ninety-four;

live operations, and the transactional ISO world editor;

rollback paths, performance budgets, and automated compatibility audits.

• a server-authoritative shard with SQLite WAL persistence, spatial indexes,
• a PixiJS browser client with the classic UO experience plus negotiated
• standard-client interoperability in both directions through the untouched UO
• one hundred persistent game-system definitions, including six dedicated
• a consolidated admin suite with Content Studio, documentation, asset tools,
• bounded caches, batched persistence and broadcasts, atomic editor mutations,

Application releases follow semantic versioning from the root package.json. The private @uo/nodeuo-protocol package is versioned independently because its schema evolves without changing the product or classic UO wire version. See [CHANGELOG.md](CHANGELOG.md) for release notes.

Public Repository Status

This project is prepared for public source distribution.

make the corresponding source code available to the community under the same license terms.

world saves, accounts, passwords, shard secrets, or private player data.

• Project code is licensed as AGPL-3.0-or-later.
• Modified versions that are distributed or offered as a network service must
• The repository must not contain Ultima Online client files, generated assets,
• Contribution rules are documented in CONTRIBUTING.md.
• The full license text is in LICENSE.

What Is In This Repository

Current Direction

The priority is functional coverage against ServUO and ClassicUO behavior without copying their architecture one-to-one. Reference projects are used for parity, protocol behavior, and bug fixing; the runtime design should stay native to this repository.

Main rules:

_inventory, _movement, _spatial, and registry helpers.

pipeline are built for the web.

for VRAM/decode if you generate it with toktx.

code.

• apps/server owns the engine and world indexes.
• apps/scripts owns gameplay content.
• Scripts should use high-level api.game, api.lifecycle, api.systems,
• The client preserves UO behavior, but rendering, cache, UI, and the asset
• PNG assets are always the fallback path. .ktx2 is an optional faster path
• templates/ is reference material for audits and bug fixes, not runtime

Repository Layout

apps/
  client/         Vite + PixiJS browser client
  server/         shard, world engine, net handlers, persistence, systems
  scripts/        gameplay content and server scripting API consumers
  bridge/         WebSocket <-> raw TCP bridge for external shards
  control-panel/  Electron launcher with logs and tool buttons

packages/
  protocol/       UO binary protocol, packets, Huffman/shared helpers
  extractor/      asset pipeline: MUL/UOP -> client assets

tools/
  run-control-panel.bat  main Windows GUI launcher
  run-control-panel.sh   main Linux/macOS GUI launcher
  bats/                  Windows command launchers
  sh/                    Linux/macOS command launchers
  audit/                 ServUO/ClassicUO audits and coverage maps

docs/
  README.md              documentation index
  server-scripting.md    guide for the current server Script API

templates/
  ClassicUO/ServUO reference code, for comparison only

saves/
  world.sqlite            world and account database (SQLite WAL)
  auxiliary JSON files    houses, map edits and small subsystem state

Requirements

• Node.js >=22.23 (Node 24.18.0 LTS recommended; pinned in .nvmrc / .node-version)
• pnpm 9.12.0 through Corepack or a global install
• Windows .bat launchers or Linux/macOS .sh launchers
• A local Ultima Online Classic installation for asset extraction
• Optional Khronos KTX-Software (toktx) for .ktx2 generation

Basic check:

node -v
corepack enable
pnpm -v

Quick Start

Recommended Windows path:

tools\run-control-panel.bat

Recommended Linux/macOS path:

chmod +x tools/run-control-panel.sh tools/sh/*.sh
tools/run-control-panel.sh

The Control Panel can:

• install the dependencies needed to start the Electron launcher;
• start the server, browser client, bridge, admin panel, and extractor;
• run project install/update actions;
• check and install KTX2/toktx tooling;
• stream service logs in one window.

Terminal path for Linux/macOS:

pnpm install
UO_SRC="/path/to/Ultima Online Classic" tools/sh/extract-assets.sh
tools/sh/run-server.sh
tools/sh/run-client.sh

Terminal path for Windows:

pnpm install
$env:UO_SRC="C:\Program Files (x86)\Electronic Arts\Ultima Online Classic"
tools\bats\extract-assets.bat
tools\bats\run-server.bat
tools\bats\run-client.bat

The development client normally runs at:

http://localhost:5173

The project WebSocket server normally runs at:

ws://127.0.0.1:2593/game

Asset Pipeline

A full extraction creates:

apps/client/public/assets/

That directory contains art/gump/anim/static atlases, map chunks, statics, tiledata, hues, multi data, lights, fonts, cliloc, and manifests.

Common commands:

pnpm extract
pnpm extract:ktx2:tool:check
pnpm extract:ktx2:tool:install
pnpm extract:ktx2

pnpm extract generates PNG/JSON/bin fallback assets. pnpm extract:ktx2 converts existing PNG atlases to .ktx2 when toktx is available. The client tries KTX2 where present and falls back to PNG when the parser or file is not available.

KTX2 is mainly useful for large texture atlases: smaller transfer, lower VRAM use, and faster GPU upload after transcoding. PNG remains the required fallback and the easiest format for debugging.

Runtime Modes

Default ports:

Important PNPM Commands

Server

apps/server is the runtime engine:

quests, economy, events;

• accounts, sessions, and login;
• WebSocket and optional raw TCP listener;
• UO binary packets and protocol compatibility;
• world state: mobiles, items, sectors, parent/child indexes, persistence;
• movement, visibility, update ranges, pathfinding, and standing Z;
• combat, notoriety, poison, regen, party, guild, chat, corpses;
• systems dispatch: spells, crafting, housing, pets, PvP, rewards, bosses,
• admin panel and diagnostics.

Architectural rule: the engine should not contain concrete game content when that content can live in apps/scripts. The engine exposes APIs, indexes, and safe operations; scripts register content and behavior.

Server Scripts

apps/scripts/src is the gameplay layer:

the admin authoring/operations workbenches;

• player and admin commands;
• item definitions and item lifecycle scripts;
• NPC/mobile templates, vendors, and AI;
• skills, spells, crafting, loot tables;
• quests, regions, spawns, and events;
• a 100-system activity catalog shared by Classic UO gumps, NodeUO views, and
• JSON data in apps/scripts/src/data.

The canonical guide for the current API is:

docs/server-scripting.md

When the shard is running, the same guides are available as a searchable, responsive workbench under Admin → Docs (http://localhost:2596/docs). The page also exposes the gump model, configuration taxonomy, examples and a live inventory of the active scripts package.

The old pattern of scanning world.items or world.mobiles directly is an exception. New code should use:

• api.game for gameplay operations and indexed reads;
• api.lifecycle for hot-reload-safe commands, events, and timers;
• api.systems for engine domains;
• _inventory.js, _movement.js, _spatial.js, and _entities.js;
• declarative defineScript() for simple modules.

Client

apps/client is a web implementation of the UO client:

gumps, animation, and performance budgets.

• Vite + PixiJS v8;
• isometric WebGL renderer;
• map streaming and chunk cache;
• PNG atlases with optional KTX2/Basis;
• mobile/static animations, gumps, paperdoll, journal, macro/hotkey flow;
• dynamic lights from world and equipment;
• roof/ceiling autohide for buildings;
• UI that follows ClassicUO behavior while using DOM/WebGL-friendly patterns;
• smoke tests for protocol, UI, rendering, pathfinder, asset cache, lights,

Useful checks after renderer changes:

pnpm --filter @uo/client run smoke:roof
pnpm --filter @uo/client run smoke:light
pnpm --filter @uo/client build

Full client smoke:

pnpm --filter @uo/client run smoke

Bridge And Compatibility

The project supports three practical configurations:

browser client -> project WebSocket server
ClassicUO/Razor -> project raw TCP server
browser client -> WebSocket bridge -> external ServUO/RunUO raw TCP shard

This lets the browser client evolve without abandoning protocol compatibility, and it lets the server be tested with native clients.

Data And Saves

Local saves live in:

saves/world.sqlite
saves/world.sqlite-wal
saves/world.sqlite-shm

The server keeps gameplay state in memory and commits only dirty entities in batched SQLite transactions on a persistence worker. The -wal and -shm files are part of a live database; use a graceful shutdown/checkpoint or the admin backup operation instead of copying only world.sqlite while running. The first SQLite boot imports legacy accounts plus player characters and their complete inventory/pet chains, but intentionally discards legacy NPCs and generated world objects. A new shard therefore starts clean and is populated explicitly with createworld. When the account table is empty, set UO_BOOTSTRAP_ADMIN_PASSWORD (and optionally UO_ADMIN_USER) to create the first durable Admin account; the server never invents a default password.

Locally generated assets live in:

apps/client/public/assets/

These paths are environment data. Do not treat them as source-of-truth review material unless you are intentionally testing persistence migration or the asset pipeline.

Documentation

Development Workflow

Before a larger change:

git status --short
pnpm test

After server changes:

pnpm --filter @uo/server test

After client changes:

pnpm --filter @uo/client build
pnpm --filter @uo/client run smoke:client-perf

After script changes:

pnpm --filter @uo/server test
pnpm audit:servuo:map:check

After asset pipeline changes:

pnpm extract:ktx2:tool:check
pnpm --filter @uo/extractor run ktx2:dry-run

Contributions

Before opening a pull request:

• read CONTRIBUTING.md;
• explain what changed and why;
• include tests or manual verification;
• keep refactors, features, and data changes separate where practical;
• do not add generated assets, world saves, or private data;
• make sure the contribution can be licensed as AGPL-3.0-or-later.

Coding Rules

facade exists.

use api.game.item.move, api.game.mobile.move, or api.game.mobile.teleport.

batching, caches, atlases, lazy loading, dirty regions, and fixed-row virtual lists are preferred.

code.

• Do not migrate scripts back to the old raw runtime API.
• Do not scan world.items or world.mobiles in hot paths when an indexed
• Do not assign item.parent or mob.x/y/z/map directly from gameplay code;
• Script registrations should be hot-reload-safe through api.lifecycle.
• The client should preserve UO behavior, but implementation can be web-native:
• templates/ is for audits, comparisons, and bug fixing; it is not runtime

License And Legal Notes

Project code is licensed as AGPL-3.0-or-later. The intent is simple: you may use, copy, host, and modify the project, but project changes should return to the community under the same terms when distributed or offered over a network.

This repository does not distribute Ultima Online files. Asset extraction requires your own legal copy of the UO client. Original code in this repository is a separate implementation; for any files ported from or based on external projects, respect the licenses noted in headers, history, and documentation.