Effects on NPCs a partner leads

Why

Every NPC NightCoop syncs is led by one player — its owner, usually the host. The others see a copy: an NPC without its own AI that only plays what the owner's NPC does (position, animation, health, death). Whatever your mod does to a copy with its own script is local:

• a status effect on a copy shows only on your screen, and the owner's NPC never had it — its AI does not react;
• a hit, a push, a slow-down or a change of side on a copy is overwritten by the owner's stream within a frame;
• Kill() on a copy does nothing for anybody else; the NPC keeps fighting at the owner.

So a quickhack mod that slows the target (CHRONOLOCK), pushes it (POLARITY), makes it fight for you (Possession) or burns it from inside (SYSTEM FRY), a weapon that lifts enemies (REPULSOR) — all work in single player and do nothing in a session, unless the owner of the NPC does the same thing. These calls ask the owner to do it with the game, as an action of your player: there, the instigator is your player's body, so the NPC's AI turns on you, its death is yours (kill credit, XP, "on kill" effects), and everybody sees the result on their copies.

What NightCoop already carries by itself

You do not need these calls for what goes through the game's own paths:

What you have to send

Anything your script does to an NPC beyond the record: ApplyStatusEffect in your redscript, QueueEvent of a ragdoll or an impulse, SetIndividualTimeDilation, AttitudeAgent.SetAttitudeTowards / SetAttitudeGroup, Kill, damage you compute yourself. Call the matching function instead of (or, for statuses, in addition to) doing it on the copy.

How the call answers:

• Your own NPC (you lead it), or an NPC NightCoop does not sync: done here at once, the same way (instigator: your player). Returns NCSDK_OK (0). The partners' copies get the look as above.
• A partner's NPC: a request to its owner. Returns the request number (> 0). The answer comes as hooks.npcResult / the event NpcResult (NCSDK_POLL_NPC_RESULT, 8) with that number in request, the effect in effect and the result in a: NCSDK_OK, or NCSDK_E_UNKNOWN (the record is not in their game, the NPC is gone), NCSDK_E_DENIED (they do not lead it any more — look it up again with entityRef and ask the new owner), NCSDK_E_STATE (your body is not near it, it is dead, the game does not ragdoll it or does not let it die now), NCSDK_E_LIMIT, NCSDK_E_OFF.
• Refused at once (negative): NCSDK_E_ARG (a bad effect, or the entity is a player's body or a vehicle), NCSDK_E_UNSUPPORTED (a kind or flag this NightCoop does not know), NCSDK_E_UNKNOWN (no such entity, the record is not in your game), NCSDK_E_STATE (not in the same world with the owner, the owner's passport is not known yet), NCSDK_E_DENIED (no USES_NPC_REQUESTS, the owner has not your mod with your protocol, or the host switched mods off for the session), NCSDK_E_LIMIT (over NCSDK_NPC_RATE_PER_S), NCSDK_E_OFF (the player's switch sdk_npc).

When you leave. A status or a slow-down the owner put on its NPC from your body comes off when you leave its world (main menu, a load, your own campaign, the end of the session): your body — its instigator — is gone. A follow role waits for you to come back; a god mode and a follow role of a player who left the session are removed.

The owner checks every request again on its side (a partner's data is untrusted, see ../SECURITY.md): it leads that NPC, both of you are in its world, your body is there and within NCSDK_NPC_NEAR_M (150 m), the record is in its TweakDB with the right class (StatusEffect / Attack), and the rate per mod and partner.

Status effects: the copy, the owner and damage ticks

By default NpcStatus also puts the status on your own copy, from your player — the way the game does for a quickhack. That gives you the look right away, and if the status deals damage over time, its ticks on your copy are your hits: they reach the owner as your damage claims. The owner's own ticks of a status from your body write no health (that would count it twice), exactly as for quickhacks. If your mod already applied the status to the copy itself (for example the status comes from your quickhack record), pass NCSDK_NPC_SKIP_LOCAL (script NightCoopSdkNpcFlag.SkipLocal).

Damage

value is health points as you see them on your copy; NightCoop turns it into a share of the copy's max health and the owner takes the same share of its NPC (machines may differ in difficulty and level). With NCSDK_NPC_PERCENT it is a percent. With an attack record, the owner builds a real hit of that attack from your body (its type, flags and effects, the NPC's hit reaction); without one, it writes the health directly, and NCSDK_NPC_REACT with mode = a gamedataAttackType gives a hit reaction. point and vector are world space at the call (point (0,0,0) — the chest); NightCoop sends the point relative to the NPC, since your copy may lag behind the owner's NPC by metres. NCSDK_NPC_NONLETHAL defeats instead of killing.

Damage of your drones, turrets and spawns

NightCoop sends the owner only hits whose instigator is your player: the game's damage pipeline on your machine counts them, the owner applies them. A hit of your mod's drone, turret or spawned NPC on a copy is not your player's — it stays on your copy (the owner never hears of it). Compute it in your mod and send it with NpcDamage (with the attack record of the drone's weapon, so the NPC reacts as to that weapon); the owner applies it from your body, and the kill is yours.

Your own world's time: worldSlow

A mod that slows or stops the whole world (bullet time, a stasis field, a time-stop implant, AMM's freeze) does it on its own machine with TimeSystem.SetTimeDilation or TimeDilationHelper. In a session that is a problem: partners keep their time and see you run in slow motion, NightCoop takes a world standing still for more than 0.3 s for a loading screen and holds the whole session in a loading pause, and in co-op TimeDilationHelper profiles are switched off (the game's own multiplayer rule, kept by NightCoop for menus).

Declare it first: worldSlow(mod, dilation, seconds) (script WorldSlow(id, dilation, seconds), Lua mod:worldSlow(d, s); needs NCSDK_MOD_USES_WORLD_TIME, UsesWorldTime, 67108864), dilation 0..1 (0 — stopped) for up to NCSDK_WORLD_SLOW_MAX_S (120) seconds; dilation 1 when it is over. Then slow the world yourself as you do in single player. While it is declared:

• partners near you (within NightCoop's implant radius) get the same slow-down as from a Sandevistan: their world slows, your body moves at your pace there; a stop reaches them as almost stopped (0.02);
• a world standing still this way is no loading screen — neither yours nor theirs;
• TimeDilationHelper.SetTimeDilationWithProfile is not switched off for you.

It is your own world only: to freeze one NPC use NpcSlow with 0.

The general request: your own logic on the owner's machine

When no fixed effect fits — your mod tracks its own state per NPC, spawns a field around it, plays a sound on it, chains a hack to its squad — send your own message about the NPC to the machine that leads it:

1. npcRequest(mod, entity, channel, data, size) (script NpcRequest(id, npc, channel, text) / NpcRequestBytes). Always returns a request number (> 0): also for your own NPC, then the request comes to your own mod on this machine. One code path for every NPC.
2. The owner's copy of your mod gets hooks.npcRequest / the event NpcRequest (NCSDK_POLL_NPC_REQUEST, 7) with its local NPC in entity, the asker in peer, your channel in a, your data, and a request number of its own in request. Do it there with the game.
3. It answers with npcReply(mod, request, result, data, size) (script NpcReply(id, request, result, text)); you get the NpcResult event with your request number, effect 0 and its data.

Answer every request once. The owner keeps at most NCSDK_NPC_PENDING_MAX (256) open requests per mod; an older one is answered NCSDK_E_LIMIT for you. Requests of a player who left are forgotten. Data is at most NCSDK_NPC_DATA_MAX (1024) bytes each way. Treat the data like any partner data: check every value.

Example 1 (redscript): a quickhack that slows its target

Your quickhack record already puts its status on the copy (so SkipLocal); the slow-down your effector did on the copy is asked from the owner.

@if(ModuleExists("NightCoop"))
import NightCoop.*

// Your effector, after the status is on the target
@if(ModuleExists("NightCoop"))
private func CoopSlow(target: ref<NPCPuppet>, status: TweakDBID) -> Void {
  let id = "you.chronolock";
  NightCoopSdk.NpcStatus(id, target.GetEntityID(), status, EnumInt(NightCoopSdkNpcFlag.SkipLocal));
  NightCoopSdk.NpcSlow(id, target.GetEntityID(), 0.2, 6.0);
}

@if(!ModuleExists("NightCoop"))
private func CoopSlow(target: ref<NPCPuppet>, status: TweakDBID) -> Void {
  target.SetIndividualTimeDilation(n"ChronoLock", 0.2, 6.0); // without NightCoop
}

Register once with the flag: NightCoopSdk.RegisterMod("you.chronolock", "Chronolock", "1.2", 1, EnumInt(NightCoopSdkModFlag.NeededByAll) | EnumInt(NightCoopSdkModFlag.UsesNpcRequests)).

Example 2 (redscript): your own logic through the general request

A "possession" hack: the owner's mod turns the NPC to your side and starts its own timer to give it back.

@if(ModuleExists("NightCoop"))
public class PossessionCoop extends ScriptableSystem {
  private let m_id: String = "you.possession";

  private func OnAttach() -> Void {
    NightCoopSdk.RegisterMod(this.m_id, "Possession", "2.0", 1,
      EnumInt(NightCoopSdkModFlag.NeededByAll) | EnumInt(NightCoopSdkModFlag.UsesNpcRequests));
    NightCoopSdk.Listen(this.m_id, this, n"OnCoopEvent");
  }

  // Called by your hack on any NPC — a copy or your own
  public func Possess(npc: ref<NPCPuppet>, seconds: Float) -> Void {
    NightCoopSdk.NpcRequest(this.m_id, npc.GetEntityID(), 1, FloatToString(seconds));
  }

  private cb func OnCoopEvent(ev: ref<NightCoopSdkEvent>) -> Bool {
    if ev.kind == EnumInt(NightCoopSdkEventKind.NpcRequest) && ev.a == 1 {
      // Here we lead the NPC: do it with the game, the asker's side
      let seconds = StringToFloat(ev.data);
      if seconds <= 0.0 || seconds > 60.0 {
        NightCoopSdk.NpcReply(this.m_id, ev.request, EnumInt(NightCoopSdkResult.BadArgument), "");
        return true;
      }
      NightCoopSdk.NpcSide(this.m_id, ev.entity, EnumInt(NightCoopSdkNpcSide.Join)); // ours: done at once
      this.StartRelease(ev.entity, seconds);                                         // your own timer, here
      NightCoopSdk.NpcReply(this.m_id, ev.request, 0, "");
    } else if ev.kind == EnumInt(NightCoopSdkEventKind.NpcResult) && ev.a != 0 {
      NightCoopSdk.Log(this.m_id, 1, "possession refused: " + IntToString(ev.a));
    }
    return true;
  }

  private func StartRelease(npc: EntityID, seconds: Float) -> Void { /* DelaySystem → NpcSide(..., Own) */ }
}

Note that NpcSide on the owner's machine is a call on its own NPC: done at once, from the owner's player. If the side must be the asker's, use the effect directly from the asker (NpcSide on the copy) — the owner then does it from the asker's body; the general request is for logic NightCoop has no effect for.

C

NcSdkNpcEffect e = {sizeof e};
e.kind = NCSDK_NPC_IMPULSE;
e.point = hitPoint;                 /* world */
e.vector = (NcSdkVec3){dir.x * 40, dir.y * 40, 12};
e.value = 2.0f;                     /* influence radius, m */
int32_t r = api->npcEffect(mod, npcEntityHash, &e);
/* r == 0: done here; r > 0: wait for hooks.npcResult(..., aRequest == r, ...) */

NcSdkHooks.npcRequest(ctx, from, entity, ref, request, channel, data, size) and npcResult(ctx, owner, entity, ref, request, effect, result, data, size) are in the hooks; without them the items go to the poll queue (NcSdkPolled.request, NcSdkPolled.effect).

CET (Lua)

local mod = Sdk.new("you.repulsor", "Repulsor", "1.0", 1, Sdk.FLAG.NEEDED_BY_ALL + Sdk.FLAG.USES_NPC_REQUESTS)
-- on hit:
mod:npcImpulse(npc:GetEntityID(), {pos.x, pos.y, pos.z}, {0, 0, 25}, 3)
mod:npcStatus(npc:GetEntityID(), "BaseStatusEffect.Stun")
-- in onUpdate: mod:poll(function(ev) if ev.kind == Sdk.EVENT.NPC_RESULT then ... ev.request, ev.a ... end end)

What is not here

• Handing the NPC to you. A possessed NPC stays with its owner: its AI is the owner's, you steer it by requests. A mod that wants to drive an NPC every frame (Possession's direct control) should ask once with the general request and let the owner's copy of the mod run it there. Handing the NPC over for the time of the possession is not in this version.
• Copies of shared spawns (entityShare) get statuses and hiding, not the push (their ragdoll is the mod's).

The switches that turn these parts off are in troubleshooting.md.