> ## Documentation Index
> Fetch the complete documentation index at: https://hyperscape-ai-mintlify-docs-update.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Game Systems Overview
> How Hyperscape game systems work
## Systems Architecture
Hyperscape game logic is implemented through **Systems** — classes that process entities and components each game tick. Systems are organized by domain and split between client, server, and shared execution contexts.
```
packages/shared/src/systems/
├── client/ # Client-only systems (rendering, input)
├── server/ # Server-only systems (auth, database)
└── shared/ # Shared systems (combat, economy, skills)
├── character/ # Character management
├── combat/ # Combat mechanics (20+ files)
├── death/ # Death and respawn
├── economy/ # Banks, shops, inventory
├── entities/ # Entity lifecycle
├── infrastructure/
├── interaction/ # Player interactions
├── movement/ # Movement, collision, pathfinding
├── presentation/ # Visual effects
├── tick/ # Game tick processing
└── world/ # World management
```
***
## System Base Class
All systems extend `SystemBase` which provides:
* Dependency management (required/optional systems)
* Lifecycle hooks (init, update, cleanup)
* World reference for entity queries
* Auto-cleanup on destroy
```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
// From packages/shared/src/systems/shared/SystemBase.ts
export class CombatSystem extends SystemBase {
constructor(world: World) {
super(world, {
name: "combat",
dependencies: {
required: ["entity-manager"],
optional: ["mob-npc"],
},
autoCleanup: true,
});
}
}
```
***
## Core Game Systems
### Combat System
**Location:** `systems/shared/combat/`
The combat system implements OSRS-style tick-based combat with 20+ supporting files:
| File | Purpose |
| --------------------------- | ---------------------------------------- |
| `CombatSystem.ts` | Main combat orchestration (\~2100 lines) |
| `DamageCalculator.ts` | OSRS damage formulas |
| `AggroSystem.ts` | Mob aggression behavior |
| `CombatStateService.ts` | Combat state management |
| `CombatAnimationManager.ts` | Attack animations |
| `CombatRotationManager.ts` | Entity facing |
| `CombatAntiCheat.ts` | Cheat detection |
| `CombatRateLimiter.ts` | Attack rate limiting |
| `PlayerDeathSystem.ts` | Player death handling |
| `MobDeathSystem.ts` | Mob death and drops |
| `RangeSystem.ts` | Ranged combat |
| `PidManager.ts` | Player ID priority (OSRS PID) |
Combat runs on a 600ms tick cycle, matching Old School RuneScape exactly.
### Economy Systems
**Location:** `systems/shared/economy/`
Handles all economic interactions:
* **Banking** — Deposit, withdraw, note conversion
* **Shops** — Buy/sell with general stores
* **Inventory** — 28-slot management with stacking
* **Loot** — Item drops and ground items
### Movement & Collision System
**Location:** `systems/shared/movement/`
Implements tile-based movement and OSRS-accurate collision:
* **TileSystem.ts** — Grid-based coordinate system
* **CollisionMatrix.ts** — Zone-based collision storage (8×8 tile zones)
* **CollisionFlags.ts** — Bitmask flags (BLOCKED, WATER, OCCUPIED, walls)
* **EntityOccupancyMap.ts** — Entity tracking with collision integration
* **BFSPathfinder.ts** — Breadth-first search pathfinding around obstacles
* **ChasePathfinding.ts** — Combat chase behavior
* **WanderBehavior.ts** — NPC wandering AI
**Collision Features:**
* Static object blocking (trees, rocks, stations)
* Multi-tile footprints (2×2 furnaces, large resources)
* Directional walls (for future dungeons)
* Network synchronization (zone serialization)
* Safespotting mechanics (OSRS-accurate)
### Character Systems
**Location:** `systems/shared/character/`
Player character management:
* **Stats tracking** — Levels, XP, combat level
* **Equipment** — Gear slots and bonuses
* **Skills** — 11 trainable skills (5 combat, 3 gathering, 3 artisan)
* **Prayer** — Prayer point management, drain mechanics, altar recharging
***
## Combat Constants
The combat system uses OSRS-accurate constants:
```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
// From packages/shared/src/constants/CombatConstants.ts
export const COMBAT_CONSTANTS = {
// Tick System
TICK_DURATION_MS: 600,
// Ranges (tiles)
MELEE_RANGE: 2,
RANGED_RANGE: 10,
PICKUP_RANGE: 2.5,
// Combat Timing (ticks)
DEFAULT_ATTACK_SPEED_TICKS: 4, // 2.4 seconds
COMBAT_TIMEOUT_TICKS: 17, // 10.2 seconds
HEALTH_REGEN_INTERVAL_TICKS: 100, // 60 seconds
// Damage Formulas (OSRS)
BASE_CONSTANT: 64,
EFFECTIVE_LEVEL_CONSTANT: 8,
DAMAGE_DIVISOR: 640,
MIN_DAMAGE: 0,
MAX_DAMAGE: 200,
// XP Rates
XP: {
COMBAT_XP_PER_DAMAGE: 4,
HITPOINTS_XP_PER_DAMAGE: 1.33,
CONTROLLED_XP_PER_DAMAGE: 1.33,
},
// Death
DEATH: {
ANIMATION_TICKS: 8,
COOLDOWN_TICKS: 17,
DEFAULT_RESPAWN_TOWN: "Central Haven",
},
} as const;
```
### Level Constants
```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
// From packages/shared/src/constants/CombatConstants.ts
export const LEVEL_CONSTANTS = {
DEFAULT_COMBAT_LEVEL: 3,
MIN_COMBAT_LEVEL: 3,
MAX_LEVEL: 99,
XP_BASE: 50,
XP_GROWTH_FACTOR: 8,
COMBAT_LEVEL_WEIGHTS: {
DEFENSE_WEIGHT: 0.25,
OFFENSE_WEIGHT: 0.325,
RANGED_MULTIPLIER: 1.5,
},
} as const;
```
***
## Skills System
Hyperscape implements 17 skills with OSRS-accurate mechanics:
### Combat Skills
| Skill | Purpose |
| ---------------- | --------------------------------------- |
| **Attack** | Melee accuracy and weapon requirements |
| **Strength** | Melee damage |
| **Defense** | Damage reduction and armor requirements |
| **Constitution** | Health points (HP) |
| **Ranged** | Ranged combat accuracy and damage |
| **Magic** | Spellcasting accuracy and damage |
| **Prayer** | Protection prayers and combat buffs |
### Gathering Skills
| Skill | Purpose |
| --------------- | ------------------------- |
| **Woodcutting** | Chop trees for logs |
| **Fishing** | Catch fish at water spots |
| **Mining** | Mine ore from rocks |
### Artisan Skills
| Skill | Purpose |
| ---------------- | --------------------------------------------------- |
| **Firemaking** | Light fires from logs |
| **Cooking** | Cook raw fish for healing |
| **Smithing** | Smelt ores into bars and smith equipment |
| **Crafting** | Create leather armor, dragonhide, jewelry, cut gems |
| **Fletching** | Create bows, arrows, and arrow components |
| **Runecrafting** | Convert essence into runes at mystical altars |
### Support Skills
| Skill | Purpose |
| ----------- | ------------------------------- |
| **Agility** | Movement and shortcuts (future) |
Each skill has independent XP tracking and levels 1-99 following OSRS XP curves. Crafting, Fletching, and Runecrafting were added in February 2026 with full OSRS-accurate mechanics.
***
## Attack Styles
Players choose how combat XP is distributed:
| Style | XP Distribution |
| -------------- | ----------------------- |
| **Accurate** | Attack + Constitution |
| **Aggressive** | Strength + Constitution |
| **Defensive** | Defense + Constitution |
| **Controlled** | Equal split across all |
***
## Mob Aggression
```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
// From packages/shared/src/constants/CombatConstants.ts
export const AGGRO_CONSTANTS = {
DEFAULT_BEHAVIOR: "passive",
AGGRO_UPDATE_INTERVAL_MS: 100,
ALWAYS_AGGRESSIVE_LEVEL: 999, // Ignores level difference
} as const;
```
| Behavior | Description |
| --------------------- | ---------------------------------- |
| **Passive** | Never attacks first |
| **Aggressive** | Attacks players in detection range |
| **Level-gated** | Ignores high-level players |
| **Always Aggressive** | Attacks regardless of level |
***
## Event System
Systems communicate through typed events:
```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
// Event types from packages/shared/src/types/events/events.ts
export enum EventType {
// Combat
COMBAT_START = "combat:start",
COMBAT_END = "combat:end",
DAMAGE_DEALT = "damage:dealt",
// Inventory
INVENTORY_ADD = "inventory:add",
INVENTORY_REMOVE = "inventory:remove",
// Skills
XP_GAINED = "xp:gained",
LEVEL_UP = "level:up",
// ... many more
}
```
***
***
## Detailed Documentation
OSRS-accurate damage formulas, attack styles, aggro system, and death mechanics. Includes melee, ranged, and magic combat.
Player-versus-player dueling with rules negotiation, item stakes, and arena combat.
RuneScape XP curves, leveling, combat level formula, and skill requirements.
Prayer mechanics, drain formulas, combat bonuses, altars, and bone burying.
Discrete tile-based movement, pathfinding, and OSRS melee range rules.
How NPCs and mobs are defined with drop tables and aggro behaviors.