Ultima Online Node

Node/Web implementation of an Ultima Online shard and browser client. The project started as a functional migration from ServUO and ClassicUO patterns, but the goal is an independent codebase: compatible with the UO protocol where that is useful, and designed for Node.js, WebSocket, PixiJS, and modern browser rendering.

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

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 CODE_0.
• 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 CODE_0.
• The full license text is in CODE_0.

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:

CODE0, CODE1, CODE_2, and registry helpers.

pipeline are built for the web.

for VRAM/decode if you generate it with CODE_0.

code.

• CODE_0 owns the engine and world indexes.
• CODE_0 owns gameplay content.
• Scripts should use high-level CODE0, CODE1, CODE_2,
• The client preserves UO behavior, but rendering, cache, UI, and the asset
• PNG assets are always the fallback path. CODE_0 is an optional faster path
• CODE_0 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/
  local world/account saves

Requirements

• Node.js CODE_0
• pnpm CODE_0 through Corepack or a global install
• Windows CODE0 launchers or Linux/macOS CODE1 launchers
• A local Ultima Online Classic installation for asset extraction
• Optional Khronos KTX-Software (CODE0) for CODE1 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/CODE_0 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

CODE0 generates PNG/JSON/bin fallback assets. CODE1 converts existing PNG atlases to CODE2 when CODE3 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

CODE_0 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 CODE_0. The engine exposes APIs, indexes, and safe operations; scripts register content and behavior.

Server Scripts

CODE_0 is the gameplay layer:

• 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;
• JSON data in CODE_0.

The canonical guide for the current API is:

docs/server-scripting.md

The old pattern of scanning CODE0 or CODE1 directly is an exception. New code should use:

• CODE_0 for gameplay operations and indexed reads;
• CODE_0 for hot-reload-safe commands, events, and timers;
• CODE_0 for engine domains;
• CODE0, CODE1, CODE2, and CODE3;
• declarative CODE_0 for simple modules.

Client

CODE_0 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.json
saves/accounts.json

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 CODE_0;
• 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 CODE_0.

Coding Rules

facade exists.

use CODE0, CODE1, or CODE_2.

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 CODE0 or CODE1 in hot paths when an indexed
• Do not assign CODE0 or CODE1 directly from gameplay code;
• Script registrations should be hot-reload-safe through CODE_0.
• The client should preserve UO behavior, but implementation can be web-native:
• CODE_0 is for audits, comparisons, and bug fixing; it is not runtime

License And Legal Notes

Project code is licensed as CODE_0. 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.