@casual-simulation/aux-common


Core shared library for CasualOS (formerly AUX). This package provides foundational types, utilities, and infrastructure used across all CasualOS components.

Overview

aux-common is the foundation of the CasualOS platform, containing:

- Bot System: Core bot state management, calculations, actions, and events
- Partitions: Pluggable storage backends for bot state (memory, Yjs CRDT, remote sync)
- WebSockets: Real-time communication infrastructure for multi-user collaboration
- RPC Framework: Type-safe remote procedure calls with comprehensive error handling
- Documents: Collaborative document abstractions using Yjs CRDTs
- Math Utilities: Vector, quaternion, and rotation classes for 3D graphics
- Common Types: Actions, events, connections, permissions, and versioning
- Records: Data record management and WebPush notifications
- Forms: Form validation and error handling
- State Machines: State machine abstractions for complex workflows
- Yjs Utilities: Helper functions and IndexedDB persistence for CRDTs

Installation

``bash
npm install @casual-simulation/aux-common
`

Package Structure

`
aux-common/
├── bots/ # Core bot system (RuntimeBot, actions, events, calculations)
├── partitions/ # Storage backends (Memory, Yjs, Remote, OtherPlayers)
├── websockets/ # WebSocket clients and inst records protocol
├── common/ # Shared types (actions, connections, versioning)
├── rpc/ # Type-safe RPC framework with error codes
├── documents/ # Collaborative document abstractions (Yjs)
├── math/ # Vector2/3, Quaternion, Rotation classes
├── records/ # Data records and WebPush notifications
├── yjs/ # Yjs helper functions and IndexedDB persistence
├── http/ # HTTP interface types
├── forms/ # Form validation and errors
├── state-machine/ # State machine abstractions
├── polyfill/ # Browser polyfills
├── utils.ts # General utility functions
├── Errors.ts # Error types and handling
├── Event.ts # Event system
└── AppVersion.ts # Version management
`

Core Modules

$3

The bot system is the heart of CasualOS, representing interactive objects with tags and behaviors.

Key Exports:

- RuntimeBot: Core bot interface with tags and state
- BotActions: Actions for creating, updating, and removing bots
- BotCalculations: Calculate bot properties (positions, rotations, colors)
- BotEvents: Event types (onClick, onCombine, onDrag, etc.)
- BotIndex: Fast lookup tables for bot queries
- StateUpdatedEvent: Bot state change events

Example:

`typescript
import {
createBot,
botAdded,
calculateBotValue,
} from '@casual-simulation/aux-common';

const bot = createBot('player1', {
name: 'Alice',
position: { x: 0, y: 0, z: 0 },
color: '#ff0000',
});

const name = calculateBotValue(null, bot, 'name'); // "Alice"
`

See bots/README.md for detailed documentation

$3

Partitions provide pluggable storage backends for bot state, enabling different persistence and synchronization strategies.

Key Exports:

- AuxPartition: Base partition interface
- MemoryPartition: In-memory storage (fast, volatile)
- YjsPartition: Local Yjs CRDT with IndexedDB persistence
- RemoteYjsPartition: Networked Yjs with server synchronization
- OtherPlayersPartition: Multi-user player state aggregation
- PartitionAuthSource: Authentication coordination

Example:

`typescript
import { createMemoryPartition } from '@casual-simulation/aux-common';

const partition = createMemoryPartition({
type: 'memory',
initialState: {},
});

partition.onBotsAdded.subscribe((bots) => {
console.log('Bots added:', bots);
});
`

See partitions/README.md for detailed documentation

$3

WebSocket infrastructure for real-time communication and inst records synchronization.

Key Exports:

- ConnectionClient: Base WebSocket client interface
- AuthenticatedConnectionClient: Authentication wrapper
- InstRecordsClient: Inst records protocol (branch watching, updates, device actions)
- WebsocketEvents: Complete protocol message types
- MemoryConnectionClient: In-memory client for testing

Example:

`typescript
import { InstRecordsClient } from '@casual-simulation/aux-common';

const instClient = new InstRecordsClient(connectionClient);

const updates$ = instClient.watchBranchUpdates({
recordName: 'myRecord',
inst: 'myInst',
branch: 'main',
});

updates$.subscribe((event) => {
if (event.type === 'updates') {
console.log('Received updates:', event.updates);
}
});
`

See websockets/README.md for detailed documentation

$3

Foundational types and utilities used throughout CasualOS.

Key Exports:

- Action: Base action type
- RemoteActions: Device actions and results
- ConnectionInfo: Connection metadata
- ConnectionIndicator: Connection tokens and credentials
- CurrentVersion: Version vectors for synchronization
- StatusUpdate: Progress and status messages
- DenialReason: Permission denial reasons

Example:

`typescript
import type {
Action,
ConnectionInfo,
CurrentVersion,
} from '@casual-simulation/aux-common';

const action: Action = {
type: 'show_toast',
message: 'Hello, world!',
};
`

See common/README.md for detailed documentation

$3

Type-safe remote procedure call framework with comprehensive error handling.

Key Exports:

- RPCResult: Result types (success/error)
- ErrorCodes: 100+ standardized error codes
- RPCError: Error type with code and message
- Procedure types: GetAccountInfoProcedure, CreateRecordProcedure, etc.

Example:

`typescript
import type { GetAccountInfoProcedure } from '@casual-simulation/aux-common';

const result = await client.call('getAccountInfo', {});

if (result.success) {
console.log('User:', result.data.user);
} else {
console.error('Error:', result.errorCode, result.errorMessage);
}
`

$3

Collaborative document abstractions using Yjs CRDTs.

Key Exports:

- YjsSharedDocument: Local Yjs document with persistence
- RemoteYjsSharedDocument: Networked Yjs with server sync
- SharedMap, SharedArray, SharedText: Collaborative data structures

Example:

`typescript
import { YjsSharedDocument } from '@casual-simulation/aux-common';

const doc = new YjsSharedDocument({
type: 'yjs',
branch: 'my-doc',
});

const map = doc.getMap('data');
map.set('key', 'value');
`

See documents/README.md for detailed documentation

$3

Vector, quaternion, and rotation classes for 3D graphics and spatial calculations.

Key Exports:

- Vector2: 2D vectors with arithmetic and geometric operations
- Vector3: 3D vectors with cross product and direction constants
- Quaternion: Quaternion representation of rotations
- Rotation: High-level rotation interface with multiple construction methods

Example:

`typescript
import { Vector3, Rotation } from '@casual-simulation/aux-common';

const position = new Vector3(1, 2, 3);
const direction = position.normalize();

const rotation = new Rotation({
axis: new Vector3(0, 0, 1),
angle: Math.PI / 2,
});
`

See math/README.md for detailed documentation

$3

Yjs utilities and IndexedDB persistence for CRDTs.

Key Exports:

- YjsIndexedDBPersistence: Local storage with automatic trimming
- getStateVector: Get version vector from Yjs document
- createRelativePositionFromStateVector: CRDT-safe positions
- getTextChar: Character-level text access

Example:

`typescript
import {
YjsIndexedDBPersistence,
getStateVector,
} from '@casual-simulation/aux-common';
import * as Y from 'yjs';

const doc = new Y.Doc();
const persistence = new YjsIndexedDBPersistence('my-doc', doc);

await persistence.whenSynced;
console.log('Document loaded from IndexedDB');

const stateVector = getStateVector(doc);
console.log('State:', stateVector);
`

See yjs/README.md for detailed documentation

Usage Examples

$3

`typescript
import {
createBot,
botAdded,
botUpdated,
createMemoryPartition,
} from '@casual-simulation/aux-common';

// Create partition
const partition = createMemoryPartition({
type: 'memory',
initialState: {},
});

// Add bot
await partition.applyEvents([
botAdded(
createBot('bot1', {
name: 'My Bot',
color: '#ff0000',
})
),
]);

// Update bot
await partition.applyEvents([
botUpdated('bot1', {
tags: { color: '#00ff00' },
}),
]);

// Subscribe to changes
partition.onBotsUpdated.subscribe((updates) => {
console.log('Bots updated:', updates);
});
`

$3

`typescript
import {
createBot,
createCalculationContext,
calculateFormulaValue,
} from '@casual-simulation/aux-common';

const bot1 = createBot('test1', {
quantity: 10,
});
const bot2 = createBot('test2', {
quantity: 5,
});
const bot3 = createBot('test3', {
quantity: 5,
});

const context = createCalculationContext([bot1, bot2, bot3]);

const formula = '=math.sum(getBotTagValues("#quantity"))';
const result = calculateFormulaValue(context, formula);

console.log(result); // 20
`

$3

`typescript
import {
createBot,
calculateFormulaEvents,
} from '@casual-simulation/aux-common';

const state = {
test1: createBot('test1', { quantity: 10 }),
test2: createBot('test2', { quantity: 5 }),
test3: createBot('test3', { quantity: 5 }),
};

const formula =
let total = math.sum(getBotTagValues("#quantity"));
player.toast("The total is " + total);
;
const events = calculateFormulaEvents(state, formula);

for (let event of events) {
if (event.type === 'local') {
if (event.name === 'show_toast') {
console.log('[Toast]', event.message);
}
}
}
// Outputs: [Toast] The total is 20
`

$3

`typescript
import {
InstRecordsClient,
AuthenticatedConnectionClient,
createRemoteClientYjsPartition,
} from '@casual-simulation/aux-common';

// Set up connection
const authClient = new AuthenticatedConnectionClient(baseClient, authSource);
const instClient = new InstRecordsClient(authClient);

// Create remote partition
const partition = await createRemoteClientYjsPartition(
{
type: 'yjs_client',
client: instClient,
recordName: 'project',
inst: 'workspace',
branch: 'main',
},
authSource
);

partition.connect();

// Watch for updates
partition.onBotsAdded.subscribe((bots) => {
console.log('Bots added:', bots);
});
`

$3

`typescript
import {
Vector3,
Rotation,
calculateBotValue,
} from '@casual-simulation/aux-common';

const bot = createBot('player', {
position: { x: 1, y: 2, z: 3 },
rotation: { x: 0, y: 0, z: Math.PI / 4 },
});

const position = calculateBotValue(null, bot, 'position') as Vector3;
const rotation = calculateBotValue(null, bot, 'rotation') as Rotation;

const forward = new Vector3(0, 1, 0);
const worldForward = rotation.rotateVector3(forward);

const newPosition = position.add(worldForward.multiplyScalar(5));
`

Architecture

`
┌─────────────────────────────────────────────────────────────┐
│ CasualOS │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Application Layer │ │
│ │ (aux-vm, aux-runtime, aux-web, casualos-cli) │ │
│ └────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌────────────────────▼───────────────────────────────┐ │
│ │ @casual-simulation/aux-common │ │
│ ├────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────────┐ ┌───────────┐ ┌──────────────┐ │ │
│ │ │ Bots │ │Partitions │ │ WebSockets │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Actions │ │ Memory │ │ InstRecords │ │ │
│ │ │ Events │ │ Yjs │ │ Connection │ │ │
│ │ │ Calcs │ │ Remote │ │ Auth │ │ │
│ │ └──────────┘ └───────────┘ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────┐ ┌───────────┐ ┌──────────────┐ │ │
│ │ │ RPC │ │ Documents │ │ Math │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Errors │ │ SharedMap │ │ Vector2/3 │ │ │
│ │ │ Results │ │ SharedText│ │ Quaternion │ │ │
│ │ │ Procs │ │ Yjs CRDT │ │ Rotation │ │ │
│ │ └──────────┘ └───────────┘ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────┐ ┌───────────┐ ┌──────────────┐ │ │
│ │ │ Common │ │ Yjs │ │ Records │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Actions │ │ Helpers │ │ WebPush │ │ │
│ │ │ Connect │ │ IndexedDB │ │ Policies │ │ │
│ │ │ Versions │ │ Persist │ │ Schemas │ │ │
│ │ └──────────┘ └───────────┘ └──────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
`

Key Concepts

$3

CasualOS uses a bot-centric model where everything is a bot with tags:

- Bots: Objects with ID and tags (key-value pairs)
- Tags: Properties that define bot behavior and appearance
- Actions: Events that modify bot state
- Calculations: Compute derived properties from tags

$3

Storage is abstracted through partitions:

- Memory: Fast, volatile in-memory storage
- Yjs: Local CRDT with IndexedDB persistence
- Remote: Networked CRDT with server synchronization
- OtherPlayers: Multi-user player state aggregation

$3

Multi-user collaboration via:

- Yjs CRDTs: Conflict-free replicated data types
- WebSocket Protocol: Inst records protocol for updates
- State Vectors: Track document versions
- Operational Transforms: Apply edits at specific versions

$3

Type safety across the stack:

- RPC Framework: Type-safe remote procedures
- Zod Schemas: Runtime validation
- Error Codes: Standardized error handling
- Observable Streams: RxJS for reactive programming

License

AGPL-3.0-only

Related Packages

- @casual-simulation/aux-runtime: Runtime execution engine
- @casual-simulation/aux-vm: Virtual machine implementations
- @casual-simulation/aux-web: Web application UI
- @casual-simulation/aux-records: Server-side record management
- @casual-simulation/casualos-cli`: Command-line interface

Contributing

See DEVELOPERS.md for development guidelines.

Version

Current version: 3.8.1

See CHANGELOG.md for version history