GHOSTWORK

Your terminal is your weapon. Your rig is your character sheet.
Your operating system is your class.

A single-player hacking simulation where you build your rig, choose your OS, and breach procedurally generated networks using real methodology — all through a fully diegetic CRT terminal interface.

$ Game Pillars

Five design principles govern every system in GHOSTWORK. No feature ships unless it serves at least one pillar.

• 01
  Accessible Depth — Three tiers of realism let anyone play. A script kiddie sees guided prompts; an APT operator sees raw protocol. The simulation underneath is identical.
• 02
  Authentic Methodology — Real cybersecurity methodology as core gameplay: reconnaissance, scanning, enumeration, exploitation, privilege escalation, and post-exploitation. Every tool and workflow reflects actual practice.
• 03
  Agency Through Systems — Interconnected systems create emergent strategy. Hardware, heat, economy, factions, and contracts interact in ways the player discovers, not ways the designer prescribes.
• 04
  The Interface Is The Game — No menus floating over the game world. The CRT terminal is your entire interface. Seven mood states drive atmosphere through the shader alone — no HUD icons, no alert popups.
• 05
  Progression Crosses Thresholds — Tier advancement is a shift in working depth, not a power increase. Everything the player does at T3, the machine was already doing at T1 on their instruction. Advancing means taking the controls.

$ How to Play

The Core Loop

GHOSTWORK operates on three nested loops that create its gameplay rhythm:

Getting Started

When you boot GHOSTWORK for the first time:

1. Choose your OS — each has a distinct visual identity and gameplay modifiers. LinuxForge is a solid default; PhantomBSD rewards stealth play.
2. Choose your tier — start at Tier 1 (Script Kiddie) if you're new to hacking games. You can switch tiers at any time.
3. Type help to see available commands. Type man <command> for detailed usage on any command.
4. Type contracts to browse the BBS board. View a contract with contracts <number>. Accept one with contracts accept <number>.
5. Complete the contract — scan, connect, exploit, extract. Monitor your heat throughout.
6. Get paid, upgrade, repeat. Use upgrade to browse hardware. Use rig to see your current setup.

The CRT Experience

There are no menus. There is no HUD. The CRT shader reacts to gameplay through seven distinct mood states:

$ Tier System

Tiers control abstraction depth, not difficulty. The simulation engine is identical at every tier. Tier determines how information is presented and how much the system does on your behalf. Switch freely at any time.

$ Operating Systems

Six operating systems, each with a distinct philosophy, visual identity, and gameplay personality. Your OS choice affects your phosphor palette (CRT color theme), window manager style, starting hardware, and gameplay modifiers.

Phosphor Palettes

Each OS defines 10 semantic color keys that control the CRT visual identity:

$ Hardware & Rig

Your hardware is your character sheet. Six slots, three upgrade tiers each. Every component creates real mechanical constraints that shape your approach. Hardware upgrades are purchased from the market — gated by contracts_completed, not by tier.

$ Commands

GHOSTWORK ships with 139 verb commands across twenty categories. Every command has a base_heat cost (noise generated) and base_ticks cost (time consumed). Type help for a full listing or man <command> for detailed usage.

$ Contracts

Contracts are jobs posted to an anonymous BBS (Bulletin Board System). Each contract is posted by a faction handle, has a risk level, payout, time limit, and one to four objectives. GHOSTWORK ships with 45 contracts spanning all four factions and three risk levels.

Contract Lifecycle

AVAILABLE → ACCEPTED → ACTIVE → PENDING_EXTRACT → COMPLETE
                                             |
                                    FAILED / ABANDONED

You can only run one active contract at a time. Completed contracts are appended to your permanent history.

Objective Types

Grading

Contracts grade you on three dimensions: stealth (low heat at completion), speed (ticks used vs. time limit), and precision (clean execution). Your approach matters as much as your success — a sloppy victory pays less than a clean one.

Risk Levels

Procedural Networks

Every target network is procedurally generated with guaranteed solvability — at least two viable attack vectors exist for every objective. Networks have active defenses: intrusion detection systems, sysadmin AI that learns your patterns, firewalls that adapt, and honeypots that trap the careless.

$ CVE Catalog

GHOSTWORK features a fictional vulnerability catalog using the ZD-YYYY-NNNN identifier format. Every exploitable service in the game maps to one or more catalog entries, each with a severity score, affected versions, and exploit requirements.

Catalog Entry Structure

Players discover vulnerabilities through scan (finds affected services), cross-reference them with the catalog using exploit --list, and target specific entries with exploit ZD-YYYY-NNNN. At T3, players can chain vulnerabilities for multi-stage attacks.

Exploit Resolution

When a player targets a vulnerability, the engine evaluates: Does the target run the affected service? Is the version in range? Does the player meet the tier and tool requirements? Success probability factors in the player's rig, OS modifiers, and the target's patch level — a fully patched host is immune.

$ Heat & OpSec

Every action generates noise. Every tool leaves traces. The Heat system creates constant tension between getting the job done and staying invisible.

Multi-Dimensional Heat

Heat is tracked on two independent dimensions. Each action specifies which dimension it affects:

Both dimensions use the same 0–100 scale and band system. Some actions affect BOTH dimensions. Detection triggers when either dimension enters the HIGH band — a stealthy network approach means nothing if you leave forensic evidence everywhere.

Heat Bands

Heat sources: every command has a base_heat value. Aggressive actions (exploits, brute-force) generate more heat. Passive actions (ls, cat, pwd) generate less. Your OS may modify heat generation — PhantomBSD generates 25% less, LinuxForge 10% less.

Heat scope: tracked per contract. Completing a contract resets heat, but residual_heat can carry over based on how sloppy the exit was.

Decay: heat decays passively on every tick-advancing command, but the rate depends on your current band. Higher heat = slower decay. Use scrub to reduce network heat by cleaning traces, and use forensic tools to manage host heat.

Idle Heat & Alert Fatigue

Inactive sessions still generate small amounts of heat — open connections are detectable. Extended idle time in a high-security network triggers sysadmin patrol checks. Conversely, defenders suffer alert fatigue: sustained medium-heat activity can cause IDS operators to lower their guard, slightly reducing detection sensitivity over time.

Surveillance Countermeasures

High-security targets deploy active surveillance: traffic analysis, behavioral profiling, and honeypot networks. Counter-surveillance commands let you detect and evade these measures — but counter-surveillance itself generates heat.

Active Defense AI

Every target network has an autonomous Sysadmin AI — not a scripted boss, but a tick-scheduled defender running on its own clock. It doesn't know you're there until it observes something wrong.

The sysadmin's routine is deterministic and learnable. Read auth.log timestamps to reconstruct patrol intervals. Notice when credentials rotate to predict the next window. The defender never cheats — they only react to what they can observe in ground truth. Your job is to read their patterns and work around them.

$ Forensic Evidence

Every action you take on a target system can leave forensic evidence — artifacts that persist after you disconnect. Evidence accumulates independently of heat and can be discovered during incident response, potentially leading to contract failure or law enforcement attention even after a successful extraction.

Evidence Types

Clean extraction matters. Use scrub for log cleanup, carefully remove tools you deployed, and avoid leaving persistence mechanisms behind unless the contract requires it. A clean post-exploitation phase reduces your evidence footprint and improves contract grades.

Volatile Artifacts

Five additional evidence types persist only in host RAM — cleared by reboot but detectable by memory forensics tools. The tradeoff: a reboot erases volatile evidence but generates noise that alerts the Sysadmin AI. See Memory Forensics for full details.

$ Law Enforcement

Sloppy operations attract attention beyond the target's defenders. The Law Enforcement Pressure system tracks cumulative evidence across contracts. Get traced too many times or leave too much evidence, and you'll face escalating consequences.

Pressure Levels

Pressure decays slowly over time through clean operations. Lying low, completing stealth contracts, and doing work for Cold Iron (security contractors) can actively reduce pressure. The scrub and evidence management commands are your primary tools for keeping the heat off.

Evidence-Chain Investigation

Law enforcement doesn't just track a scalar "heat" score. The Evidence Linker correlates patterns across contracts — same technique, same tools, same network range, overlapping timing, traceable cryptocurrency. Each pattern spawns an investigation thread with its own strength that builds over time. See Evidence Chains for full details.

$ Economy

Credits (CR) are earned from contracts and spent on hardware upgrades. The economy uses an append-only transaction ledger — every income and expense is permanently recorded.

Use wallet to check your balance. The market is gated by contracts_completed, not tier. Better hardware requires finishing more jobs.

Cryptocurrency

Some contracts pay in cryptocurrency instead of (or in addition to) credits. Crypto earnings are stored in a separate wallet with its own volatility mechanics — the exchange rate fluctuates based on in-game market conditions.

$ Cloud Resources

The 2039 internet runs on consolidated cloud infrastructure. Cloud targets represent high-value contract objectives with their own attack surface, distinct from traditional on-premise networks.

Cloud Providers (In-Game)

Software Tools

Cloud CLIs and infrastructure tools must be installed before use. Use install <tool> to download and configure tools to your rig. Each tool consumes storage space and some require minimum hardware tiers.

$ Web Application Attacks

Full OWASP Top 10 attack surface simulation. Every web application on a target host is modeled with routes, parameters, and vulnerability types. A configurable WAF (Web Application Firewall) tracks failed injection attempts and blocks attackers who trigger too many alerts.

Attack Surface Model

Workflow

nikto / gobuster → discover routes and params → sqlmap / burp fuzz → exploit injectable params → extract data or pivot. Each step generates heat (NETWORK dimension). Stealth flags and tool bonuses modify success chances.

$ Privilege Escalation

Misconfiguration-based privilege escalation — the most common real-world attack vector after initial access. Hosts now have privesc vectors: SUID binaries, sudo rules, writable cron jobs, and interesting file paths.

GTFOBins Database

12 binary entries (nmap, find, vim, python3, perl, less, awk, env, bash, cp, tar, wget) with SUID and sudo exploitation methods. Each entry specifies the command sequence for shell escape.

Vectors

$ Supply Chain Attacks

Package registry simulation with full dependency trees, integrity checking, and social engineering. Registries live at the topology level (shared infrastructure, not per-host), supporting npm, PyPI, RubyGems, and Cargo ecosystems.

Attack Vectors

Blast Radius

Every supply chain attack computes a blast radius score (0–100) based on direct dependents, transitive dependents, and weekly downloads. Higher blast radius means higher payout — and higher heat.

$ PKI & Encryption Infrastructure

Deep TLS/SSL simulation. Every service can have a TLS configuration with protocol version, cipher suite, key strength, HSTS, and certificate chain. The system grades each configuration A through F, matching real-world assessment methodology.

Grading Criteria

Attack Chain

sslscan → identify weak TLS config → sslstrip (if no HSTS) or MITM via weak protocol → intercept credentials or forge certificates. MITM requires same-subnet positioning. Certificate forging requires stolen CA key material and works only against weak (512-bit) RSA keys.

$ Player Scripting

At T3, players unlock the scripting runtime — the ability to write and execute automation scripts that chain commands together. Scripts are stored on your rig's local storage and executed via the script command.

Capabilities

Scripts are stored as plaintext on your rig's STORAGE — storage capacity limits how many scripts you can carry. Use ls ~/scripts to manage them.

$ TCP/IP Simulation

Every network action generates real packet metadata. The PacketLedger is a ring buffer (2000-packet capacity, configurable) that records every packet emitted by NSS action handlers — bridging the TrafficAnalysis IDS and powering tcpdump.

Packet Record

Protocol Helpers

High-level methods emit realistic packet sequences for common operations:

Commands

$ Payload Modules

Metasploit-style exploit/payload separation. CVEs define what breaks; payloads define what happens next. Twelve payload modules span shell, advanced shell, web, persistence, and data exfiltration categories.

Payload Properties

Tier-Based Workflow

Commands

$ Encoding & Evasion

Encoding transforms payloads and packets to evade detection. Six encoders span T1 through T3, each trading size increase and reliability loss for IDS/AV evasion. A 0.95 detection floor ensures there is always some chance of getting caught.

Encoder Catalog

Stacking & Diminishing Returns

Stack up to 3 encoders. Each additional layer applies at 50% effectiveness:

# Effective IDS evasion with 3-stack
Layer 1: 100% effectiveness
Layer 2: 50% effectiveness
Layer 3: 25% effectiveness
Cap:     0.95 maximum — always some detection chance

Command

$ Evidence Chains

Law enforcement doesn't track a single number. The Evidence Linker correlates patterns across contracts, spawning investigation threads that build strength over time — exactly how real LE builds cases through TTPs, tool reuse, and blockchain analysis.

Link Types

Thread Lifecycle

DORMANT → ACTIVE → HOT → CLOSING
   strength 0-25   25-50   50-80   80-100

Thread strength maps to existing LE pressure levels. Threads decay per-contract (clean operations reduce strength). Identity Wipe burns threads with strength < 60 and weakens all others by 50 points.

$ Memory Forensics

Five volatile evidence types live in host RAM, not on disk. They survive session disconnect but are cleared by reboot or service restart — creating a strategic tradeoff between evidence cleanup and operational noise.

Volatile Evidence Types

Commands

$ Attack Graph

BloodHound-style network visualization. A GraphEdit-based panel shows your discovered attack surface as an interactive graph — hosts as nodes, sessions and credentials as edges, colored by access level.

Graph Elements

Features

• 01
  Node detail on click — known services, known vulnerabilities, evidence count, access level.
• 02
  Force-directed layout — auto-layout with manual drag repositioning.
• 03
  Filters — by subnet, access level, session status.
• 04
  Shortest path — highlight the hop chain between any two hosts.

Commands

$ SIEM Log Forwarding

Enterprise targets don't just log locally — they forward evidence to a centralized SIEM (Security Information and Event Manager). Scrubbing a compromised host's logs doesn't erase what was already forwarded. This creates a race-against-the-clock mechanic: clean your traces before the forwarding delay expires, or the evidence becomes permanent.

How It Works

Commands

$ Service Enumeration

Real pentesting doesn't jump from scan to exploit. The enumeration phase sits between reconnaissance and exploitation — probing services for version strings, banners, login prompts, and directory listings that improve your attack accuracy.

Enumeration Bonus

Enumerating a service before exploiting it grants an additive exploit success bonus (typically +5% to +15%, depending on the protocol). Unenumerated exploits still work at base rate, but you're leaving accuracy on the table.

Commands

$ Signature-Based IDS

TrafficAnalysis now combines anomaly detection (volume-based) with signature matching (pattern-based). Fifteen signature rules watch for specific protocol+port+flag combinations that indicate known attack patterns.

How Signatures Work

Evasion Mechanics

Encoding your payloads reduces signature match probability via the ids_evasion stat. Polymorphic encoders (shikata_ga_nai, custom_packer) get a 2× evasion multiplier against signatures specifically — their re-randomizing nature defeats static pattern matching.

$ Deep Encryption & PKI Operations

Beyond basic TLS scanning, GHOSTWORK now simulates certificate chain-of-trust, HSTS enforcement, cert pinning, mutual TLS, and certificate forgery. High-security targets use layered cryptographic defenses that must be peeled back methodically.

Attack Chain

1. certutil inspect <host> — scan the TLS configuration: protocol version, cipher suite, key strength, security flags, CA chain.
2. If HSTS is absent: sslstrip can downgrade HTTPS connections to intercept credentials.
3. If cert pinning blocks MITM: exfiltrate the target's CA private key from the filesystem, then certutil forge --ca-key <path> --target <host> to forge a trusted certificate.
4. With a forged cert: MITM attacks bypass cert pinning on that host. Intercepted traffic is visible.

Commands

$ BBS Economy & Poster Reputation

The BBS board is no longer a passive job listing. Poster handles have reputation scores, contracts use escrow, jobs can expire from competing operators, and some posters are law enforcement fronts.

Poster Trust

Every poster has a trustScore (0–100) and confirmedJobs count. Trust shifts based on contract outcomes — completing a job raises trust, failing or abandoning lowers it.

Escrow System

When accepting a contract, the player deposits an escrow fee (15% of base payout, minimum 25 CR). Escrow is returned on successful completion, forfeited on failure or abandonment. Trusted posters (≥75 trust) offer a 50% escrow discount.

Contract Expiry

Contracts on the BBS board can expire after 200 ticks — taken by competing operators. This creates urgency: desirable contracts won't wait for you. A living underground market where you're not the only player.

LE Sting Operations

$ Active Directory

Domain attack chains modeled after real Active Directory penetration testing. Extract Kerberos tickets, replicate credentials via DCSync, and forge golden tickets for persistent domain admin access. All AD actions are configured via active_directory_config.json.

Attack Chain

kerberoast (extract TGS tickets) → dcsync (replicate creds, capture krbtgt) → golden_ticket (forge TGT, persistent admin)
                                                                                      ↑
                              pass_the_ticket (replay stolen tickets on domain-joined hosts)

Commands

Domain Model

Hosts with an ad_domain property are domain controllers. The domain defines service accounts (with SPNs for Kerberoasting), credential rotation intervals, and GPO update cycles. Stolen credentials and tickets are tracked per-host in the _ad_stolen state dictionary.

$ Wireless Attacks

WiFi and Bluetooth attack surface covering wireless encryption cracking, rogue access points, and deauthentication attacks. Protocol difficulty scales realistically: WEP is trivial, WPA2-PSK is moderate, WPA3-SAE is near-impossible without specific conditions. Configured via wireless_config.json.

Commands

Wireless AP Model

Hosts with a wireless_ap property are access points. The AP defines SSID, protocol (WEP/WPA2/WPA3-SAE), signal strength, connected clients, and channel. Protocol type determines the difficulty multiplier for aircrack and whether deauth can capture usable handshakes (WPA3-SAE uses SAE exchange, making captured handshakes less useful).

$ Assessment & Proctor Mode

GHOSTWORK includes a built-in proctored assessment system for cybersecurity education. Instructors run a proctor dashboard that connects to student game instances over a local network, enabling real-time monitoring, controlled lab environments, and automated grading.

How It Works

Assessment Scenarios

Six built-in scenarios cover core cybersecurity skills. Each defines objectives, time limits, and grading weight distribution.

4-Axis Grading

Every assessment is graded on four dimensions, each weighted per scenario:

Letter grades: A ≥ 90%, B ≥ 80%, C ≥ 70%, D ≥ 60%, F < 60%.

Instructor Controls

$ New Game Plus

After completing the main progression, NG+ unlocks a second cycle with retuned difficulty. Your credits, faction reputation, and hardware carry over — but contracts hit harder, network defenses scale up, and heat thresholds tighten.

$ Accessibility

GHOSTWORK is a text-heavy game — accessibility is not an afterthought. The following features are built in from day one:

All accessibility settings persist across sessions independently of game saves.

$ Localization

GHOSTWORK ships with 6 languages. All UI screens use the translation system — no hardcoded user-facing strings.

$ Factions

Four factions operate in the underground, each with their own philosophy, contract style, and moral boundaries. Building reputation with a faction unlocks better contracts and deeper narrative threads.

$ World Timeline

The year is 2039. The internet you knew is gone. Cloud consolidation, government surveillance acts, and corporate monopolies have reshaped the digital landscape. The underground is the last free space — and it's under siege.

$ Modding Guide

GHOSTWORK supports a comprehensive addon system that lets modders add, extend, and override nearly every content type in the game. Addons are data-driven — most modifications require only JSON files, with optional GDScript for custom command logic.

Directory Structure

user://addons/
  my_custom_addon/
    addon.json          # Required manifest
    commands/           # Custom verb definitions
      recon_tool.json
      recon_tool.gd     # Optional: custom executor
    contracts/          # Custom contracts
    factions/           # New or extended factions
    hardware/           # New hardware components
    os/                 # New operating systems
    narrative/          # Story fragments
    music/              # Music tracks (tracks.json)
    shell/              # Shell presets (presets.json)
    cves/               # Custom vulnerability catalog entries
    tools/              # Custom software tools
    market/             # Custom market items
    ids_signatures/     # IDS signature rules
    service_banners/    # Service enumeration banners
    poster_profiles/    # BBS poster profiles
    encoders/           # Custom encoding definitions
    configs/            # Config overrides (deep merge)

Operations: Add, Extend, Override

Every content type supports up to three operations:

Load Order & Priority

1. Core game content loads first. This is the baseline.
2. Addon extensions apply in load_order sequence (lower numbers first).
3. First override wins. If two addons override the same content, the lower load_order takes priority.

$ Manifest Schema

Every addon requires an addon.json manifest at its root:

{
  "id": "my_recon_pack",              // Unique identifier (snake_case)
  "name": "Recon Tool Pack",            // Human-readable display name
  "version": "1.0.0",                  // SemVer version
  "author": "YourName",                 // Author or team
  "description": "Adds recon tools",     // Short description
  "game_version_min": "1.0.0",          // Minimum game version required
  "dependencies": [],                    // Other addon IDs this depends on
  "load_order": 100,                     // Lower = loads earlier (default: 100)
  "content": {                            // Maps content types to directories
    "commands":   "commands/",
    "contracts":  "contracts/",
    "factions":   "factions/",
    "hardware":   "hardware/",
    "narrative":  "narrative/",
    "music":      "music/",
    "shell":      "shell/",
    "cves":       "cves/",
    "tools":      "tools/",
    "market_items": "market/",
    "ids_signatures": "ids_signatures/",
    "service_banners": "service_banners/",
    "poster_profiles": "poster_profiles/",
    "encoders":  "encoders/",
    "configs":   "configs/"
  }
}

$ Modding: Commands

Add new terminal commands, extend existing ones with new flags or subcommands, or fully override a built-in command.

Adding a New Command

Create a JSON verb definition in your addon's commands/ directory:

// commands/port_knock.json
{
  "verb_id": "port_knock",
  "signature": "port_knock <host> <ports...>",
  "base_heat": 2,
  "base_ticks": 1,
  "widget_kind": "text_output",
  "intent_template": "Knock on ports {ports} at {host}",
  "execute_key": "port_knock",
  "presentation_tier": 2,
  "description": "Send a port knock sequence to open filtered services"
}

Register it in your manifest:

"content": {
  "commands": {
    "add": [
      { "file": "commands/port_knock.json" }
    ]
  }
}

Custom Command Logic (GDScript)

For commands that need custom behavior beyond the standard pipeline, place a GDScript executor alongside the JSON:

# commands/port_knock.gd
extends VerbExecutor

func execute(args: Dictionary, context: CommandContext) -> VerbResult:
    var host := args.get("host", "") as String
    var ports := args.get("ports", []) as Array
    # Custom logic here
    return VerbResult.success("Knocked: %s" % [", ".join(ports)])

Data-Only Commands (Aliases)

Simple aliases need no GDScript — use alias_target:

{
  "verb_id": "nk",
  "alias_target": "port_knock",
  "description": "Shorthand for port_knock"
}

Extending Existing Commands

"commands": {
  "extend": [
    {
      "verb_id": "scan",
      "add_flags": ["--stealth", "--deep"],
      "add_subcommands": ["vuln"]
    }
  ]
}

Overriding Commands

"commands": {
  "override": [
    {
      "verb_id": "scan",
      "file": "commands/custom_scan.json"
    }
  ]
}

$ Modding: Contracts

Add new contracts with custom network topologies, extend existing contracts, or override them.

Adding a Contract

{
  "id": "custom_heist_01",
  "title": "The Vault Job",
  "poster_handle": "silkthread",
  "briefing": "Meridian needs corporate R&D data. Hardened internal network. Get in, get files, get out clean.",
  "risk_level": "HIGH",
  "base_payout": 8000,
  "time_limit_ticks": 200,
  "target_security_level": 3,
  "faction_tag": "meridian_group",
  "objectives": [
    {
      "type": "FILE_EXFILTRATE",
      "target_file": "/data/research/project_alpha.db",
      "description": "Extract Project Alpha database"
    },
    {
      "type": "SESSION_ESTABLISH",
      "target_host": "10.0.1.50",
      "description": "Persistent access to backup server"
    }
  ],
  "sysadmin_config": {
    "base_patrol_interval_ticks": 40,
    "hosts_inspected_per_patrol": 2,
    "credential_rotation_interval_ticks": 150,
    "patch_cycle_interval_ticks": 100,
    "enabled": true
  },
  "network": {
    "topology": "star",
    "hosts": [
      { "ip": "10.0.1.1", "role": "gateway", "services": ["ssh", "http"] },
      { "ip": "10.0.1.10", "role": "workstation", "services": ["smb"] },
      { "ip": "10.0.1.50", "role": "server", "services": ["ssh", "ftp", "postgres"] }
    ]
  }
}

The sysadmin_config field is optional. If omitted, the Active Defense AI difficulty is derived from target_security_level. Set "enabled": false to disable the defender entirely for your contract.

Hosts may include web_apps (attack surfaces for nikto/sqlmap), privesc_vectors (SUID/sudo/cron for linpeas), and tls_config (cipher suites for sslscan).

Extending Contracts

"contracts": {
  "extend": [
    {
      "id": "existing_contract_id",
      "patch": {
        "briefing": "Updated briefing text...",
        "add_objectives": [
          { "type": "CUSTOM_CONDITION", "description": "Leave no logs" }
        ],
        "add_hosts": [
          { "ip": "10.0.1.99", "role": "honeypot" }
        ]
      }
    }
  ]
}

$ Modding: Factions

Add entirely new factions, extend existing ones, or override (warned — affects narrative coherence).

Adding a Faction

{
  "faction_id": "neon_circuit",
  "display_name": "Neon Circuit",
  "type": "hacktivist",
  "description": "Digital artists turned hacktivists. Code is art, art is resistance.",
  "handle": "pixel_prophet",
  "rivals": ["meridian_group"],
  "allies": ["signal_collective"],
  "contract_style": "Digital art installations on corporate networks",
  "will_not_do": ["Destroy creative works", "Target independent artists"]
}

Extending a Faction

"factions": {
  "extend": [
    {
      "faction_id": "signal_collective",
      "add_rivals": ["neon_circuit"]
    }
  ]
}

$ Modding: Hardware

Add new hardware components to any of the six slots, extend existing components, or override.

Adding Hardware

{
  "component_id": "quantum_nic",
  "slot": "NIC",
  "tier": 4,
  "display_name": "Quantum NIC",
  "price": 15000,
  "effects": {
    "scan_depth": 4,
    "scan_speed_multiplier": 0.5
  },
  "prerequisites": {
    "contracts_completed": 30
  },
  "description": "Quantum-entangled network interface. Sees everything."
}

Extending Hardware

"hardware": {
  "extend": [
    {
      "component_id": "gpu_3",
      "add_effects": { "hash_rate_bonus": 0.5 },
      "add_prerequisites": { "faction_rep_undermarket": 50 }
    }
  ]
}

$ Modding: Operating Systems

Add entirely new operating systems with custom phosphor palettes, window manager models, starting hardware, and gameplay modifiers.

Adding an OS

{
  "os_id": "iron_os",
  "display_name": "IronOS",
  "shorthand": "IRON",
  "tagline": "Forged in fire",
  "dominant_phosphor": "red",
  "wm_model": "TILING",
  "phosphor_palette": {
    "bg": "#0a0000",
    "fg_primary": "#ff4040",
    "fg_secondary": "#cc3030",
    "accent": "#ff6020",
    "border": "#401010",
    "selection": "#602020",
    "comment": "#804040",
    "alert_low": "#ff8040",
    "alert_mid": "#ff4020",
    "alert_high": "#ff0000"
  },
  "starting_hardware": {
    "CPU": 1, "RAM": 1, "NIC": 1,
    "STORAGE": 1, "GPU": 2, "COOLING": 1
  },
  "gameplay_modifiers": {
    "heat_multiplier": 1.1,
    "cpu_speed_bonus": 0.9
  }
}

All 10 palette keys are required when adding a new OS. When extending, provide only the keys you're changing.

Extending an OS

"os": {
  "extend": [
    {
      "os_id": "linux_forge",
      "patch_palette": { "accent": "#40ff80" },
      "patch_modifiers": { "heat_multiplier": 0.85 }
    }
  ]
}

$ Modding: CVE Catalog

Add custom fictional vulnerabilities to the game's CVE catalog. All entries must use the ZD- prefix — entries without it are rejected at load time.

Adding a Vulnerability

{
  "zd_id": "ZD-2039-1001",
  "title": "QuantumDB Authentication Bypass",
  "severity": 9.1,
  "affected_service": "quantumdb",
  "affected_versions": "2.0.0-2.4.3",
  "exploit_type": "auth_bypass",
  "requires_auth": false,
  "tier_minimum": 2,
  "description": "Malformed auth token causes QuantumDB to skip credential verification."
}

Extending Existing CVEs

"cves": {
  "extend": [
    {
      "zd_id": "ZD-2038-0042",
      "patch": {
        "affected_versions": "1.0.0-3.2.1",
        "severity": 9.8
      }
    }
  ]
}

$ Modding: Software Tools

Add custom installable software tools that players can download to their rig. Tools are required by certain commands (especially cloud operations) and consume rig storage.

Adding a Tool

{
  "id": "quantum_scanner",
  "display_name": "QuantumScan",
  "description": "Advanced vulnerability scanner with quantum-accelerated pattern matching",
  "size_kb": 128,
  "required_by": ["qscan"],
  "tier_minimum": 2,
  "install_ticks": 5
}

Extending Existing Tools

"tools": {
  "extend": [
    {
      "id": "aws_cli",
      "patch": {
        "size_kb": 96,
        "required_by": ["aws", "s3cmd"]
      }
    }
  ]
}

$ Modding: Narrative

Add narrative fragments that appear as discoverable content during gameplay, each with unlock conditions.

Adding Narrative

{
  "fragment_id": "iron_lore_01",
  "title": "The Forge Master's Log",
  "content": "Day 47. The compiler is sentient. I'm sure of it now...",
  "tags": ["lore", "iron_os", "ai"],
  "unlock_conditions": {
    "contracts_completed": 10,
    "os_id": "iron_os"
  }
}

Extending Narrative

"narrative": {
  "extend": [
    {
      "fragment_id": "existing_fragment",
      "add_content": "Additional paragraph appended...",
      "add_tags": ["conspiracy"]
    }
  ]
}

$ Modding: Music

GHOSTWORK uses a 3-intensity-layer music system powered by Ovani. Every track has a main layer (always audible), an intensity_1 layer (fades in during tense moments), and an intensity_2 layer (fades in at critical heat). Layers crossfade automatically based on the game's mood system — modders provide raw audio files and metadata only.

Declare "music": "music/" in your addon manifest's content map. Inside that directory, create a tracks.json file — a JSON array of track definitions.

Track Schema

Intensities Mode (Default)

The layers object maps layer names to .ogg or .wav file paths relative to the music directory:

Example: tracks.json

// music/tracks.json
[
  {
    "id": "sample_ambient",
    "display_name": "Sample Ambient Track",
    "reverb_tail": 4.0,
    "mode": "intensities",
    "layers": {
      "main": "base_drone.ogg",
      "intensity_1": "tension.ogg",
      "intensity_2": "critical.ogg"
    }
  },
  {
    "id": "lofi_loop",
    "display_name": "Lo-Fi Loop",
    "mode": "loop30",
    "file": "lofi_30s.ogg"
  }
]

$ Modding: Shell Presets

Customize the terminal with shell presets that define command aliases and environment variables. Declare "shell": "shell/" in your addon manifest's content map, then create a presets.json file.

Example: presets.json

// shell/presets.json
{
  "extends": "default",
  "aliases": {
    "ll": "ls -la",
    "cls": "clear",
    "ports": "scan --ports"
  },
  "variables": {
    "EDITOR": "nano"
  }
}

extends inherits from the named base preset ("default" gives you all built-in aliases). Aliases expand at parse time — typing ll runs ls -la. Variables are available to commands via the shell environment.

$ Modding: Market Items

Add consumable items to the in-game market. Items provide one-shot effects like heat reduction, intel scanning, or credential reveals.

Adding a Market Item

{
  "id": "thermal_dampener",
  "name": "Thermal Dampener",
  "description": "Emergency heat dissipation module. Single use.",
  "price": 2500,
  "category": "defense",
  "effect_type": "heat_reduce",
  "effect_value": 15.0,
  "tier_required": 2,
  "reusable": false
}

Effect types: heat_reduce, scrub_all, intel_scan, credential_reveal, forged_access, heat_reduction. Items with reusable: true persist in inventory after use.

Extending Market Items

"market_items": {
  "extend": [
    {
      "id": "burner_phone",
      "patch": {
        "price": 1500,
        "effect_value": 20.0
      }
    }
  ]
}

$ Modding: IDS Signatures

Add custom intrusion detection rules to the signature-based IDS engine. Signature rules fire alongside anomaly detection during packet analysis.

Adding a Signature Rule

{
  "rules": [
    {
      "id": "SIG-ADDON-001",
      "name": "Custom Backdoor Pattern",
      "matches": {"protocol": "tcp", "dst_port_range": [31337, 31337]},
      "severity": "CRITICAL",
      "detection_base": 0.8
    }
  ]
}

Rule IDs must be unique across core and addon rules. Addon rules are appended to the core rule set during TrafficAnalysis initialization. Polymorphic encoders get 2× evasion bonus against signature detection.

Extending a Rule

{
  "rules": [
    {
      "extends": "SIG-001",
      "detection_base": 0.5,
      "severity": "MEDIUM"
    }
  ]
}

$ Modding: Service Banners

Add service banners for the enumeration system. Banners define what the enum command reveals about a service, and the enumeration bonus applied to subsequent exploits.

Adding a Banner

{
  "banners": {
    "custom_svc": {
      "defaultBanner": "CustomSvc/1.0 ready",
      "versionPattern": "CustomSvc/{version}",
      "enumerationBonus": 0.10,
      "detailFields": ["auth_required", "protocol_version"]
    }
  }
}

Banner keys match services[].type in contract host definitions. The enumerationBonus is added to exploit success rate when the service has been enumerated first.

$ Modding: Poster Profiles

Add BBS poster handles with trust scores, faction affiliations, and law enforcement front status. Poster trust affects contract risk assessment and payout reliability.

Adding a Poster

{
  "posters": {
    "addon_poster": {
      "trustScore": 60,
      "confirmedJobs": 10,
      "faction": "shadow_guild",
      "isLeFront": false,
      "bio": "A mysterious new fixer on the board."
    }
  }
}

Extending a Poster

{
  "posters": {
    "extends": "d4rkm4tter",
    "trustScore": 65,
    "bio": "Updated bio after a big job."
  }
}

$ Modding: Encoders

Add custom encoding schemes for payload evasion. Encoders interact with the IDS evasion cap (0.95), AV evasion cap (0.95), and reliability compounding per iteration.

Adding an Encoder

{
  "encoders": {
    "addon_encoder": {
      "name": "Custom Encoder",
      "tier": 2,
      "sizeMultiplier": 1.2,
      "idsEvasion": 0.45,
      "avEvasion": 0.35,
      "reliabilityPenalty": 0.08,
      "polymorphic": false,
      "description": "A custom encoding scheme."
    }
  }
}

New encoders are available to msfvenom -e at the specified tier. Use msfvenom preview to verify balance after changing evasion values.

Extending an Encoder

{
  "encoders": {
    "extends": "xor",
    "reliabilityPenalty": 0.03,
    "description": "Rebalanced XOR encoding."
  }
}

$ Modding: Config Overrides

Tune subsystem parameters without writing code. Place JSON files in your addon's configs/ directory, each targeting a core config by name.

Example: Tuning Web Attack Detection

{
  "target": "web_attack_config",
  "detectionConfig": {
    "baseWafBypassChance": 0.35
  }
}

Available Targets

Merge Rules

Scalars (strings, numbers, bools) are replaced. Dictionaries are recursively merged. Arrays are appended. Multiple addons targeting the same config merge in load order.

$ Advanced Modding

Complete Addon Example

A full addon that adds a new faction, commands, contracts, custom vulnerabilities, tools, music, and shell aliases:

// addon.json
{
  "id": "neon_circuit_pack",
  "name": "Neon Circuit Faction Pack",
  "version": "1.0.0",
  "author": "ExampleModder",
  "description": "Adds Neon Circuit faction with custom contracts and tools",
  "game_version_min": "1.0.0",
  "content": {
    "commands": "commands/",
    "factions": "factions/",
    "contracts": "contracts/",
    "cves": "cves/",
    "tools": "tools/",
    "music": "music/",
    "shell": "shell/"
  }
}

Content Type Support Matrix

Best Practices

• Prefer add over override. New content creates no conflicts. Overrides can collide.
• Use extend for small changes. Adjusting a price or adding a flag is cleaner than a full override.
• Set load_order thoughtfully. Default is 100. Content packs: 100–200. Total conversions: 900+.
• Prefix your IDs. Use neon_circuit_art_bomb not art_bomb to avoid collisions.
• Respect faction will_not_do constraints when adding contracts for existing factions.
• Follow the existing price/effect curve for hardware. Proportional improvement, not exponential.
• Include a README in your addon directory with install instructions and known incompatibilities.
• Test alongside core content. Your addon should enhance, not break, the base game.

$ Modding API Reference

Complete field-level schema for every moddable content type. Download the machine-readable spec or browse inline.

Addon Manifest (addon.json)

Content map keys: commands, contracts, factions, hardware, os, narrative, music, shell, cves, tools, market_items, ids_signatures, service_banners, poster_profiles, encoders, configs

Commands

Contracts

Factions

Hardware

Operating Systems

CVE Catalog

Software Tools

Market Items

IDS Signature Rules

Service Banners

Poster Profiles

Encoders

Config Overrides

Narrative, Music & Shell

$ GDScript Runtime API

Custom command executors are GDScript files that run alongside verb JSON definitions. This section documents the classes and methods available to addon scripts at runtime.

Verb Executor Contract

Every custom command GDScript must follow this exact contract:

# commands/my_verb.gd
extends RefCounted


static func get_verb_id() -> StringName:
    return &"my_verb"


static func execute(ctx: ExecutionContext) -> void:
    # Your logic here. ctx provides all system access.
    var vm := PresentationViewModel.new()
    vm.widget_kind = &"stream"
    vm.producer_id = "my_verb"
    vm.payload = {"lines": [{"text": "Hello from addon!"}]}
    vm.complete()
    ctx.result_vm = vm

ExecutionContext

The context object passed to every verb executor. It provides parsed arguments, injectable system seams, and the submit_and_wait() coroutine for requesting game-world actions.

submit_and_wait()

The coroutine for requesting game-world actions through the EventScheduler. Returns a Dictionary with "success": bool and action-specific result data.

var outcome: Dictionary = await ctx.submit_and_wait(
    &"scan_host",             # action name
    StringName(target_ip),    # target
    {"depth": true}           # params (optional)
)

PresentationViewModel

The output object your verb builds and assigns to ctx.result_vm. It drives the terminal widget display.

Widget Payload Formats

GHOSTWORK — A hacking simulation by Broken Sigil Studio

139 commands · 52 contracts · 6 operating systems · 18 hardware components · 52 CVEs · 12 payload modules · 6 encoders · 6 languages · 16 moddable content types