​

Player Death System Architecture

​

Overview

​

Core Features

​

1. OSRS-Style Keep-3 System

• Items are ranked by manifest value field
• Stacked items (quantity > 1) are handled efficiently without memory explosion
• Kept items are returned to inventory on respawn
• Dropped items go to gravestone for retrieval

• O(n log n) complexity on unique item slots (not individual units)
• Greedy quantity assignment for stacked items
• Deterministic tiebreaking on original index when values are equal

​

2. Two-Phase Persist Pattern

• Clear inventory and equipment in-memory
• Create death lock with kept items
• Skip database persist (would cause nested transaction deadlock)

• Persist equipment clear to database
• Persist inventory clear to database
• Retry queue handles failures

​

3. Death Lock System

interface DeathLock {
  playerId: string;
  deathPosition: { x: number; y: number; z: number };
  keptItems: InventoryItem[];  // For crash recovery
  createdAt: number;
  expiresAt: number;  // Auto-expire after 5 minutes
}

• Prevent reconnect during death processing from corrupting state
• Store kept items for crash recovery (in-memory map is lost on server crash)
• Auto-expire stale locks (TTL: 5 minutes)

​

4. Gravestone Privacy

• lootItems array is stripped from network broadcast
• Only lootItemCount (number) is synced to all clients
• Full loot data sent only to interacting player via corpseLoot packet
• Empty gravestone guard uses synced lootItemCount field

​

5. Persist Retry Queue

interface PersistRetry {
  playerId: string;
  type: 'equipment' | 'inventory';
  timestamp: number;
}

• Single retry per failure (no infinite loops)
• Retries drained once per tick in processPendingRespawns()
• Track in-flight retries to prevent races with reconnect/new death
• Bounded queue (max 100 entries) to prevent unbounded growth
• AUDIT_LOG events on retry failure for ops visibility

​

Architecture

​

File Structure

packages/shared/src/systems/shared/combat/
├── PlayerDeathSystem.ts       # Main death orchestration (1,605 lines)
├── DeathUtils.ts              # Pure utility functions
├── DeathTypes.ts              # Type definitions
└── __tests__/
    ├── PlayerDeathFlow.test.ts    # Death-to-respawn flow tests
    └── DeathUtils.test.ts         # Utility function tests (51 tests)

packages/shared/src/systems/shared/death/
├── DeathStateManager.ts       # Death lock CRUD operations
├── SafeAreaDeathHandler.ts    # Safe zone death logic
├── WildernessDeathHandler.ts  # PvP zone death logic (future)
└── ZoneDetectionSystem.ts     # Zone type detection

​

Key Components

​

PlayerDeathSystem

class PlayerDeathSystem extends SystemBase {
  // Entry point - called by PlayerSystem.handleDeath
  handlePlayerDeath(playerId: string, killedBy?: string): void

  // Core death processing (server-only)
  private async processPlayerDeath(playerId: string, killedBy?: string): Promise<void>

  // Post-death cleanup (equipment, inventory, gravestone)
  private async postDeathCleanup(playerId: string, ...): Promise<void>

  // Respawn handling
  handleRespawnRequest(playerId: string): void
  private initiateRespawn(playerId: string): void
  private respawnPlayer(playerId: string): void

  // Tick-based processing
  processPendingRespawns(): void  // Called every tick
}

​

DeathUtils

// XSS/Unicode/injection protection for killer names
function sanitizeKilledBy(killedBy: unknown): string

// OSRS keep-3 with stack handling (O(n log n) on unique items)
function splitItemsForSafeDeath(
  allItems: InventoryItem[],
  keepCount: number
): { kept: InventoryItem[]; dropped: InventoryItem[] }

// Position validation and clamping to world bounds
function validatePosition(position: Position3D): Position3D | null
function isPositionInBounds(position: Position3D): boolean

// Constants
const GRAVESTONE_ID_PREFIX = "gravestone_"
const ITEMS_KEPT_ON_DEATH = 3
const POSITION_VALIDATION = { WORLD_BOUNDS: 10000, MAX_HEIGHT: 500, MIN_HEIGHT: -50 }

​

DeathStateManager

class DeathStateManager {
  // Create death lock (with kept items for crash recovery)
  async createDeathLock(playerId: string, deathPosition: Position3D, keptItems: InventoryItem[]): Promise<void>

  // Check if player has active death lock
  async getDeathLock(playerId: string): Promise<DeathLock | null>

  // Clear death lock after respawn
  async clearDeathLock(playerId: string): Promise<void>

  // Cleanup expired locks (TTL: 5 minutes)
  async cleanupExpiredLocks(): Promise<void>
}

​

Death Flow

​

Safe Zone Death (Keep-3)

1. Player health reaches 0
   ↓
2. PlayerSystem.handleDeath() emits ENTITY_DEATH
   ↓
3. PlayerDeathSystem.handlePlayerDeath() receives event
   ↓
4. Check cooldown (prevent spam)
   ↓
5. Check duel guard (block respawn during active duel)
   ↓
6. Set deathProcessingInProgress flag (prevent race)
   ↓
7. processPlayerDeath() [SERVER-ONLY]
   ├─ Validate position (clamp to world bounds)
   ├─ Get all inventory + equipment items
   ├─ Split into kept (top 3 by value) and dropped
   ├─ Start transaction:
   │  ├─ Clear inventory in-memory (skipPersist=true)
   │  ├─ Clear equipment in-memory (skip save when tx provided)
   │  ├─ Create death lock with kept items
   │  └─ Commit transaction
   ├─ Persist equipment clear to DB (after tx)
   ├─ Persist inventory clear to DB (after tx)
   └─ Store kept items in-memory map
   ↓
8. postDeathCleanup()
   ├─ Set player state to DYING
   ├─ Emit PLAYER_SET_DEAD event
   ├─ Create gravestone entity with dropped items
   ├─ Schedule respawn timer (10 seconds)
   └─ Clear deathProcessingInProgress flag
   ↓
9. Tick-based respawn (processPendingRespawns)
   ├─ Check timer expired
   ├─ Check player still in DYING state
   ├─ Restore kept items to inventory
   ├─ Clear death lock
   ├─ Teleport to respawn point
   ├─ Reset health/prayer/combat state
   └─ Emit UI_DEATH_SCREEN_CLOSE

​

Error Recovery

• Catch in handlePlayerDeath()
• Reset player to alive state
• Revive in-place (deathPosition)
• Log error with stack trace

• Add to retry queue
• Single retry on next tick
• AUDIT_LOG event on retry failure
• Bounded queue (max 100 entries)

• Death lock persists kept items to database
• On reconnect: check for active death lock
• Emit AUDIT_LOG event (ops visibility)
• Recover kept items from death lock
• Complete respawn flow

​

Event Migration

​

PLAYER_DIED → PLAYER_SET_DEAD

world.on('PLAYER_DIED', (data: { playerId: string }) => {
  // Handle death
});

world.on('PLAYER_SET_DEAD', (data: { playerId: string; killedBy?: string }) => {
  // Handle death
});

​

Database Schema

​

death_locks Table

CREATE TABLE death_locks (
  player_id TEXT PRIMARY KEY,
  death_position_x REAL NOT NULL,
  death_position_y REAL NOT NULL,
  death_position_z REAL NOT NULL,
  kept_items TEXT NOT NULL,  -- JSON array of InventoryItem
  created_at INTEGER NOT NULL,
  expires_at INTEGER NOT NULL
);

• Primary key on player_id (one lock per player)
• Index on expires_at for cleanup queries

​

Testing

​

Unit Tests

• sanitizeKilledBy() - XSS, Unicode normalization, BiDi overrides, control characters
• splitItemsForSafeDeath() - OSRS keep-3, stack handling, edge cases, OOM regression
• validatePosition() - NaN/Infinity handling, clamping, bounds checking
• isPositionInBounds() - Boundary validation

• Duel guard blocks respawn during active duel
• Death processing race guard prevents duplicate ENTITY_DEATH
• Tick-based respawn timing
• Persist retry queue drain
• PLAYER_DIED → PLAYER_SET_DEAD migration

• modify() network sync logic
• lootItemCount=0 clears local items
• Non-zero preservation
• Missing field handling
• Null mesh safety

​

Integration Tests

• Wilderness death (lose all items)
• Safe zone death (keep 3 most valuable)
• Gravestone creation and loot retrieval
• Death lock cleanup

​

Security Considerations

​

Input Validation

• Normalize Unicode to NFKC (prevent homograph attacks)
• Remove zero-width characters (U+200B-U+200D, U+FEFF)
• Remove BiDi override characters (U+202A-U+202E)
• Remove control characters (0x00-0x1F, 0x7F)
• Remove dangerous HTML characters (<>'\"&)
• Limit to 64 characters
• Default to “unknown” for invalid inputs

• Check for NaN/Infinity
• Clamp to world bounds (±10km from origin)
• Clamp height (-50m to 500m)
• Reject completely invalid positions

• Early return for gravestone_ prefix in handlePlayerDeath()
• Prevents gravestone destruction from triggering false player death
• Performance optimization (not security boundary - real gate is isServer check)

​

Server-Only Processing

if (!this.world.isServer) {
  this.logger.warn("Client attempted server-only death processing", { playerId });
  return;
}

​

Duel Guard

const duelSystem = this.world.getSystem("duel") as DuelSystem;
if (duelSystem?.isPlayerInActiveDuel(playerId)) {
  this.logger.debug("Respawn blocked: player in active duel", { playerId });
  return;
}

​

Performance Characteristics

​

Memory

• Kept Items Map: O(n) space where n = number of dead players awaiting respawn
• Retry Queue: Bounded at 100 entries (prevents unbounded growth)
• Death Locks: One per player, auto-expire after 5 minutes

​

CPU

• splitItemsForSafeDeath(): O(n log n) on unique item slots
  • Old implementation: O(n × quantity) - expanded stacks into individual entries
  • New implementation: Operates on unique slots with greedy assignment
  • Example: 10,000 arrows = 1 slot, not 10,000 array entries
• Gravestone Cleanup: O(1) per gravestone (event-driven via CORPSE_EMPTY)
  • Fallback: Tick-based expiration in SafeAreaDeathHandler (if event is lost)

​

Monitoring & Observability

​

Audit Events

// Reconnect with active death lock (potential crash-window scenario)
world.emit("AUDIT_LOG", {
  event: "RECONNECT_WITH_DEATH_LOCK",
  playerId,
  deathLock,
});

// Persist retry failure (equipment)
world.emit("AUDIT_LOG", {
  event: "DEATH_PERSIST_RETRY_FAILED",
  playerId,
  type: "equipment",
  error: err.message,
});

// Persist retry failure (inventory)
world.emit("AUDIT_LOG", {
  event: "DEATH_PERSIST_RETRY_FAILED",
  playerId,
  type: "inventory",
  error: err.message,
});

​

Debug Logging

// Cooldown guard
this.logger.debug("Death on cooldown, ignoring", { playerId, remainingMs });

// Position fallback
this.logger.warn("Death position invalid, using player position", { playerId, deathPosition });

// Empty gravestone interaction
this.logger.warn("HeadstoneEntity.modify() received invalid lootItems", { entityId, lootItems });

​

Grep Tags

• DEATH_PERSIST_DESYNC - Persist failure after transaction commit
• AUDIT_LOG - High-severity events requiring ops attention
• [DEATH-DEBUG] - Removed in cleanup (all debug logs now use Logger system)

​

Common Issues & Solutions

​

Issue: Player stuck in death animation, never respawns

• Player plays death animation
• Death screen appears
• Respawn timer never triggers
• Player stuck in DYING state

1. Check server logs for DEATH_PERSIST_DESYNC tag
2. Check for transaction errors in death processing
3. Query death locks: SELECT * FROM death_locks WHERE player_id = ?

• Nested transaction deadlock in SQLite
• clearEquipmentAndReturn() and clearInventoryImmediate() opened transactions inside executeInTransaction()

-- Clear stuck death lock
DELETE FROM death_locks WHERE player_id = 'player_<id>';

​

Issue: Equipment duplicates on death

• Player dies
• Equipment appears in both gravestone and inventory after respawn
• Item duplication exploit

• Equipment clear failed silently due to transaction deadlock
• Gravestone created with equipment items
• Player respawned with equipment still equipped

​

Issue: Gravestone shows stale items after looting

• Player loots gravestone
• Gravestone entity persists with old items
• Next death shows duplicate items in gravestone

1. removeItem() used setTimeout(500ms) for self-destruct (unreliable)
2. getNetworkData() only sent lootItemCount, never actual items array
3. Client entity had no items → empty loot window

1. Entity destruction moved to PlayerDeathSystem.handleCorpseEmpty() via EntityManager
2. lootItems added to network data
3. modify() overridden to sync private lootItems field on client

​

API Reference

​

DeathUtils

​

sanitizeKilledBy(killedBy: unknown): string

• killedBy - Raw killer name (any type)

• Normalizes Unicode to NFKC (prevent homograph attacks)
• Removes zero-width characters
• Removes BiDi override characters
• Removes control characters
• Removes dangerous HTML characters

const safe = sanitizeKilledBy("Goblin<script>alert(1)</script>");
// Returns: "Goblinscriptalert1script"

const safe2 = sanitizeKilledBy("а\u200Bttacker"); // Cyrillic 'а' + zero-width space
// Returns: "аttacker" (normalized, zero-width removed)

​

splitItemsForSafeDeath(allItems: InventoryItem[], keepCount: number)

• allItems - All inventory + equipment items
• keepCount - Number of items to keep (typically 3)

1. Tag each item with unit value from manifest
2. Sort descending by value (tiebreak on original index)
3. Greedily assign keep-count without expanding stacks
4. Split into kept and dropped with adjusted quantities

const items = [
  { itemId: "rune_scimitar", quantity: 1 },    // value: 15000
  { itemId: "lobster", quantity: 20 },         // value: 150 each
  { itemId: "dragon_bones", quantity: 5 },     // value: 3000 each
];

const { kept, dropped } = splitItemsForSafeDeath(items, 3);
// kept: [
//   { itemId: "rune_scimitar", quantity: 1 },  // 15000
//   { itemId: "dragon_bones", quantity: 2 },   // 6000 total (2 units kept)
// ]
// dropped: [
//   { itemId: "dragon_bones", quantity: 3 },   // 3 units dropped
//   { itemId: "lobster", quantity: 20 },       // All dropped (low value)
// ]

​

validatePosition(position: Position3D): Position3D | null

• position - Position to validate

• X/Z: ±10,000 (10km from origin)
• Y: -50 to 500 (allow some underground, cap at 500m height)

const pos = validatePosition({ x: 15000, y: 1000, z: -20000 });
// Returns: { x: 10000, y: 500, z: -10000 } (clamped)

const invalid = validatePosition({ x: NaN, y: 0, z: 0 });
// Returns: null

​

isPositionInBounds(position: Position3D): boolean

• position - Position to check

isPositionInBounds({ x: 5000, y: 100, z: -3000 });  // true
isPositionInBounds({ x: 15000, y: 100, z: 0 });     // false (x out of bounds)

​

PlayerDeathSystem

​

handlePlayerDeath(playerId: string, killedBy?: string): void

• playerId - Player entity ID
• killedBy - Optional killer name (sanitized before use)

• Checks cooldown (prevent spam)
• Checks duel guard (block during active duel)
• Sets processing flag (prevent race)
• Calls processPlayerDeath() (server-only)
• Error recovery: reset to alive on failure

​

handleRespawnRequest(playerId: string): void

• playerId - Player entity ID

• Player must be in DYING state
• Respawn timer must exist

• Validates preconditions
• Calls initiateRespawn() immediately (bypasses timer)

​

processPendingRespawns(): void

• Iterate all pending respawn timers
• Check if timer expired
• Check if player still in DYING state
• Call respawnPlayer() for expired timers
• Drain persist retry queue (single retry per failure)

​

Configuration

​

Environment Variables

# Death system (no specific env vars - uses game constants)
# Respawn timer: 10 seconds (hardcoded in PlayerDeathSystem)
# Death lock TTL: 5 minutes (hardcoded in DeathStateManager)
# Persist retry queue max: 100 entries (hardcoded in PlayerDeathSystem)

​

Constants

// DeathUtils.ts
export const ITEMS_KEPT_ON_DEATH = 3;
export const GRAVESTONE_ID_PREFIX = "gravestone_";
export const POSITION_VALIDATION = {
  WORLD_BOUNDS: 10000,
  MAX_HEIGHT: 500,
  MIN_HEIGHT: -50,
};

// PlayerDeathSystem.ts
private readonly DEATH_COOLDOWN_MS = 2000;  // 2 seconds between deaths
private readonly RESPAWN_DELAY_MS = 10000;  // 10 seconds to respawn
private readonly MAX_RETRY_QUEUE_SIZE = 100;  // Bounded retry queue

​

Future Enhancements

​

Wilderness Death (PvP)

• Lose all items (no keep-3)
• Killer gets loot
• Skull system (protect item count)
• Unsafe zone detection

​

Prayer Protection

• Protect Item prayer keeps 1 additional item (keep-4 instead of keep-3)
• Requires active prayer points
• Drains prayer on death

​

Gravestone Upgrades

• Purchasable gravestones with longer TTL
• Gravestone blessing (extend timer)
• Gravestone repair (prevent decay)

​

References

• PR #1094: Player death system overhaul
• DeathUtils.ts: Pure utility functions
• DeathTypes.ts: Type definitions
• PlayerDeathSystem.ts: Main orchestration
• DeathStateManager.ts: Death lock database operations
• SafeAreaDeathHandler.ts: Safe zone death logic