Hacking and counterplay

Build multiplayer hacking abilities with server-owned definitions, grants and target validation. The following sections describe the supported implants, upload rules and Lua interfaces.

Default keys: hold F8 to upload on the aimed player, INSERT to purge yourself, DELETE to purge the aimed ally, END to cancel your own upload. Players rebind them in Pause → Settings → KEY BINDINGS; the defaults live in resources/system/open77_hacking/client/config.lua.

Minimal example#

A resource that defines one Short Circuit deck, one Self-ICE and one purge implant, and installs them on the player who runs /hackkit deck, /hackkit ice or /hackkit purge. It needs the open77_appearance character adapter and a configured database, like every cyberware resource. Hacking implants are ordinary implants: the hacking definition and a cyberware definition with the same ID, version and grade IDs.

open77.lua:

resource "my_hacking"
version "1.0.0"
dependency "open77_hacking >=0.1.0"
server_script "server/main.lua"
permissions {
    "players.hacking.define", "players.hacking.read", "players.hacking.activate",
    "players.cyberware.define", "players.cyberware.read", "players.cyberware.manage"
}

server/main.lua:

local inert = { normalDamage = 0, chargedDamage = 0, knockbackMeters = 0, cooldownMs = 100, chargeMs = 100 }
local kit = {
    deck  = { id = "myserver.short_circuit", slot = "operating_system", profile = "cyberdeck" },
    ice   = { id = "myserver.self_ice",      slot = "self_ice",         profile = "self_ice" },
    purge = { id = "myserver.purge",         slot = "purge",            profile = "active_purge" },
}

CreateThread(function()
    assert(Open77.hacking.define({ id = kit.deck.id, version = 1, grades = {
        { id = "training", range = 20, uploadMs = 2000, staminaCost = 20, cooldownMs = 5000,
          damage = 25, statusMs = 750, recoveryMs = 4000, nonlethal = true },
    }}))
    assert(Open77.hacking.defineIce({ id = kit.ice.id, version = 1, grades = {
        { id = "training", charges = 1, rechargeMs = 15000 },
    }}))
    assert(Open77.hacking.definePurge({ id = kit.purge.id, version = 1, grades = {
        { id = "training", staminaCost = 15, cooldownMs = 8000, allowSelf = true, allowAlly = true,
          range = 10, cancelUploads = true, removeStatuses = true },
    }}))
    for _, item in pairs(kit) do
        local grade = { id = "training" }
        for k, v in pairs(inert) do grade[k] = v end
        assert(Open77.cyberware.define({ id = item.id, version = 1, slot = item.slot,
            profile = item.profile, grades = { grade } }))
    end
end)

RegisterCommand("hackkit", function(source, args)
    local player, item = tonumber(source), kit[args[1] or "deck"]
    if not player or player <= 0 or not item then return end
    local record, reason = Open77.cyberware.current(player)
    if not record then print("character not ready: " .. tostring(reason)); return end
    local result, error = Open77.cyberware.install(player, item.id, "training",
        { expectedRevision = record.revision, operationId = assert(Open77.cyberware.newOperationId()) })
    print("hackkit: " .. (result and json.encode(result) or tostring(error)))
end, false)

The attacker runs /hackkit deck, waits for the installation to complete (see transactions), aims at a visible player within 20 m and holds F8 until the bar fills. The target sees an INCOMING SHORT CIRCUIT bar and a warning, and can step behind cover, leave range, damage the hacker, or press INSERT if /hackkit purge was installed. /hackkit ice makes the next upload bounce off Self-ICE. Your server's combat scope and team rules must allow the attacker to damage the target, exactly as for any other attack.

Server API#

All calls live under Open77.hacking (and Open77.statuses for the two status calls). Failures return nil, reason; mutations return {ok = true, actionId = ...}.

start and purge require options = {operationId = "..."}; reuse the ID when you retry the same call, a reused ID with different arguments is refused. Definitions belong to the resource that registered them; stopping it revokes them and cancels its uploads but leaves installed implants on the record.

Options#

Hack grade#

What each kind does#

Every block is optional (defaults in brackets). A burn is split evenly over durationMs / tickMs ticks, the first landing one tickMs after impact; totalDamage = 0 is a burn with no damage. A malfunction that lists hacking also denies the victim its own INSERT; an ally's DELETE still works.

The effects block#

Any grade can add outcomes to its connected upload:

{ id = "stun", range = 20, uploadMs = 2000, staminaCost = 20, cooldownMs = 6000,
  statusMs = 750, recoveryMs = 6000, nonlethal = true,
  effects = {
      damage = 10,              -- replaces `damage`; 0–300
      freezeMs = 2000,          -- hold the victim; 1–10000, at most recoveryMs
      knockdown = true,         -- victim to the floor; needs recoveryMs >= 1500
      disableCyberwareMs = 5000 -- Dash, Ground Slam, Gorilla, hacking and purge refused; 1–30000
  } }

knockdown and freezeMs share one hold: the victim goes to the floor once (about three seconds); a longer freeze keeps the ability gate running, and the victim's own client locks the body from the third second to the deadline. disableCyberwareMs is bound to the character, so a reconnect does not clear it; a Malfunction status, by contrast, is lifted by purge, death, reconnect and a bucket change.

Self-ICE and purge grades#

Ally purge needs both players on the same positive combat team. A purge charges its cost only when it finds something to cancel or remove, and never heals damage already dealt.

Events#

onHackingTransition(encodedJson) is the ledger of every hack. Decode the argument with json.decode: actionId, owner, attacker, target, attackerIncarnation, targetIncarnation, definition, grade, kind, phase, reason, startedAt, deadline, statusEndsAt, amount, lockHacking, from, to and, on a malfunction, blocks. Phases: challenge, upload_started, upload_progress, blocked, interrupted, impact, completed, status_applied, status_tick (one per burn tick, amount = damage committed), status_expired, status_purged, effect_applied and effect_refused.

AddEventHandler("onHackingTransition", function(encoded)
    local t = json.decode(encoded)
    if t.phase == "impact" or t.phase == "effect_applied" then
        print(("%s hacked %s: %s %s %s"):format(t.attacker, t.target, t.kind, t.phase, tostring(t.reason)))
    end
end)

Do not infer a second hit from status_applied or completed; only impact and status_tick are damage. Callbacks in one tick can arrive out of order, so correlate on actionId rather than on arrival.

Optional lab#

open77_hacking_lab (auto_start false) ships every kind as a grade of lab.short_circuit plus ICE and purge, and installs them through the cyberware APIs. Grant testers the command.hacklab ACL. With two connected, alive players 1 and 2 in bucket 0:

/hacklab attacker 1 training hacking-a-01      -- or overheat, malfunction, malfunction_motion,
                                                --    cripple, cripple_heavy, reboot_optics,
                                                --    weapon_glitch, stun, freeze_long, cosmetic
/hacklab protected 2 training hacking-b-ice-01
/hacklab ally 2 training hacking-b-purge-01
/hacklab scope 0 1 2                            -- allow PvP between the two; /hacklab unscope <id>
/hacklab state 2
/hacklab purge 2                                -- self purge from the server; /hacklab purge 2 1 for an ally
/hacklab protection 2 on 0                      -- safe area; "off 0.5" = 50% resistance
/hacklab remove 2 self_ice hacking-b-ice-remove-01

The last argument of an install or removal is the operation ID; use a new one for each new operation. The grades are in resources/gamemodes/open77_hacking_lab/server/config.lua.

Limits#

One status of each kind per victim. A second Overheat, Malfunction, Cripple, Reboot Optics or Weapon Glitch inside the first lands its direct hit and effects but its status is refused, not refreshed: effect_refused with the running deadline in statusEndsAt (status_stacked from statuses.apply). Statuses of different kinds coexist. With recoveryMs >= durationMs nobody is even admitted while the status runs.

Two halves. The slow, the blind and the jam are applied by the victim's own client; the ability refusals (cyberware_suspended, crippled, weapon_glitched, frozen) are the server's. A modified client can ignore its own slow, blind or jam, but it cannot dash, slam or arm Gorilla Arms through the gate. Reboot Optics has no server half at all.

Line of sight is client evidence. The server issues short-lived challenges to both participants and each client traces the same segment against static and dynamic collision. A missing, stale or failed trace blocks the upload. This is a shared-evidence model, not a server-side collision query: two colluding modified clients can defeat it.

The victim is always warned. Every incoming upload produces a toast, a chat warning and the native INCOMING <KIND> bar. If the victim's notification cannot be delivered the upload fails closed. Repeated challenges do not repeat the warning.

Damage is one ledger write. The direct hit is electrical (hacking_impact, no blood, no native hit reaction); resistance and safe areas reduce it. Burn ticks are thermal and ignore electrical resistance; a tick the combat rules refuse ends the burn. Purge, death, revive, reconnect, bucket change, the attacker leaving and the provider stopping all end a status; committed damage stays.

Cooldowns follow the character. Hack, purge and recovery timers are bound to the durable character across reconnects for the life of the server process; they do not survive a server restart.

Protection scopes combine. Safe-area flags union and electrical resistance takes the maximum across providers, so one resource cannot clear another's protection. Scopes expire with the body they were set on.

Advanced: presentation#

open77_hacking renders every kind with fixed identifiers; replace its server/presentation.lua to change what observers see, and client/config.lua (HackingInput.feedback = {flash = true, sound = true}) to switch the victim's flash and local sound off.

The attacker's bar shows <KIND> UPLOAD while holding, then <KIND> IMPACT; the victim's shows INCOMING <KIND>. The bar is drawn at 1.5x while it carries a hacking header. Client resources can observe a streamed target with Open77.hacking.observe(playerId) and drive the bar with present({actionId, phase, progress, kind}) / clear() behind player.hacking.project; the victim-side statuses use Open77.hacking.nativeStatus (player.hacking.status) and Open77.movement.lock (player.movement.lock). None of these grant hacking authority, and the open77:hacking:* network events cannot be sent by a resource.