API reference

Result codes

int32_t functions return NCSDK_OK (0) or a positive count/flag on success, a negative code on failure, unless noted.

Mods

NcSdkModInfo: size, flags, id, name, version, protocol, hooks (may be NULL: poll instead). Id: ASCII [a-z0-9._-], 3..64 bytes, stable forever. protocol: your own wire version; data goes only between equal numbers.

Flags (NcSdkModInfo.flags; scripts: NightCoopSdkModFlag, combined with EnumInt(A) | EnumInt(B)):

Flags are part of the passport that other players see. They describe what your mod does, and they are also its permissions: a use that is not declared answers NCSDK_E_DENIED (one log line), and partners' data of that kind for the mod is dropped. Besides the USES_* flags: entityShare / entityUnshare / entityKeepLocal need SPAWNS_ENTITIES, factKeepLocal needs CHANGES_QUESTS. Reading functions, log, showMessage, pick, cleanText and pollEvent need nothing. See ../SECURITY.md.

Log, screen, language

Marked "any thread" in the header.

log and showMessage texts are cleaned the same way by NightCoop (no line breaks: a mod's line cannot forge a line of NightCoop's log).

Session

NcSdkWhere (set size before the call):

Channels

Messages of your mod to peers that have it.

• to: a peer, the host (0) or everyone who has the mod (NCSDK_TO_ALL / -2). You are never a recipient yourself.
• channel: your own numbering, uint16_t (scripts: Int32).
• Flags: NCSDK_SEND_RELIABLE = reliable and ordered per channel (default: unreliable). NCSDK_SEND_LATEST_ONLY (C only, unreliable): of several messages on the same channel to the same peer in one frame, only the newest leaves at the end of the frame. Scripts take a reliable flag.
• Size: unreliable up to 1024 bytes, reliable up to 16384 bytes.
• Only peers whose passport lists the same id and protocol receive anything. A guest's message to another guest goes through the host, which relays it.
• Returns the number of peers it went to (0: nobody has the mod), NCSDK_E_STATE out of a session or when the passport of that very peer is not known yet, NCSDK_E_UNKNOWN for a peer not in the session, NCSDK_E_LIMIT over the rate, NCSDK_E_ARG for a bad size.

Receive with hooks.message or the Message event.

Shared state

Per mod, key to value, kept by the host, the same for everyone in the session.

• Guest: the call only sends a request. The host's mod may refuse in hooks.stateRequest (scripts cannot refuse: they accept everything). When accepted, everybody including the guest gets stateChanged with by = the guest. When refused, nothing changes and both sides write a log line.
• Joining: the host sends the whole state of the mod to the guest as soon as it knows the guest has the mod. The guest gets one stateChanged per key. Becoming a guest first clears the local state (with removal events), then the host's state arrives. The end of a session clears the state for everyone (removal events).
• Out of a session you are your own host: stateSet works locally.
• Limits: key up to 64 bytes UTF-8, value up to 4096 bytes, 256 keys per mod.
• A guest's stateSet returns NCSDK_E_STATE when the host has not answered the mods check yet, and NCSDK_E_DENIED when the host does not have the mod.
• A removal arrives as stateChanged with size 0 and data NULL (script event: removed).

Entities

Network references

NcSdkNetRef: kind, owner (who leads it now), id.

Scripts get the reference packed in a Uint64: kind 8 bits | owner 24 bits | id 32 bits (NCSDK_PACK_REF). Owner 0xFFFFFF means none.

Entity state

The main way for a port to say something about an entity: a value of your mod under a uint16_t key, attached to an entity by its owner and delivered to the mirror/copy on every other machine.

• Returns NCSDK_E_DENIED if you are not the owner, NCSDK_E_UNKNOWN for an entity NightCoop does not sync. Size up to 1024 bytes either way.
• NightCoop keeps the last value per (mod, entity, key) on the owner and on every receiver. Receivers get hooks.entityState (script event EntityState) with their local mirror/copy/body in entity.
• If the mirror is not there yet, the value waits and arrives when it appears. If the mirror is recreated (a new EntityID for the same car, NPC or body), the value is delivered again to the new one. A partner who joins later, or whose passport arrives later, gets all current values. A script mod that registers again (every load of a save makes its system anew) gets all current values again.
• Your own player is special: values on your player are kept for "our player", not for one EntityID, so they survive reloads, a new world and a new peer number. Partners get them on your body.
• If the entity is gone at the owner (the car or NPC is no longer synced or despawned), NightCoop forgets its values and tells receivers, who get a clear (size 0, removed). If the owner loses ownership (an NPC handed to another player), the values stay on the receivers until the new owner sets new ones.
• In the hook, size 0 with data NULL means the key was cleared.

Sharing and keeping local

Details of this part are in the header comments; behavior beyond them is not described here.

Vehicles a mod holds in the air

For flight mods: while a vehicle flies, NightCoop's rules for cars on the ground must leave it alone.

• The hold of a vehicle you lead is told to every partner, with or without your mod: their mirror goes by the same rules, a partner without your mod does not take its wheel (it flies on at your machine, they ride in it), and with NoWheels they see it without wheels.
• Needs NCSDK_MOD_USES_ENTITY_STATE. Release it when the vehicle lands; holds are dropped when the mod unregisters.

Hook sharedSpawn / event SharedSpawn tells that a partner's shared spawn appeared here (present 1, entity is our copy) or is gone (0). Hook spawnLeader / event SpawnLeader tells that a shared spawn changed its leader. All of it, with the recipe for CET spawns: shared-spawns.md.

Effects for partners

A partner shows it only within 150 m of your player, at most 20 a second from you, and only if the resource is in its game.

All three need NCSDK_MOD_USES_EFFECTS, are rate-limited together with effectShow, and play nothing on your own machine — play it there yourself. See shared-spawns.md.

Leading an NPC for a while

Rewards for partners

The partner checks everything: the same mod (id and protocol), your passport, the record (an item, not a quest item), 1..NCSDK_REWARD_MAX (9999), the rate (NCSDK_REWARD_PER_S 2, bursts of 8), one world, and from a guest — your player within 100 m (the host's world gives quest and gig rewards from anywhere). A lost answer is repeated; the grant is never given twice. To hand over an item you have, use NightCoop's item transfer (NightCoopGiveItem).

Pose, actions

Brief. When this part is not in the running NightCoop build, the functions return NCSDK_E_UNSUPPORTED.

Effects on NPCs a partner leads

The whole story, the table of effects and examples are in npc-effects.md. Need NCSDK_MOD_USES_NPC_REQUESTS.

NcSdkNpcEffect: size, kind (NCSDK_NPC_STATUS 1, UNSTATUS 2, DAMAGE 3, IMPULSE 4, SLOW 5, ATTITUDE 6, SIDE 7, KILL 8, FOLLOW 9, GODMODE 10, FAKE_DEATH 11, DISPOSE 12, HIDE 13; script NightCoopSdkNpcEffect; short forms NpcFollow(id, npc, follow), NpcGodMode(id, npc, mode)), flags (NCSDK_NPC_SKIP_LOCAL 1, PERCENT 2, NONLETHAL 4, REACT 8, ALL_PLAYERS 16, SHOW_ALWAYS 32, NO_ANIM 64, NO_RAGDOLL 128; script NightCoopSdkNpcFlag), mode (attitude 0 friendly, 1 neutral, 2 hostile; side NCSDK_NPC_SIDE_JOIN 0, _ALL_ENEMIES 1, _OWN 2, script NightCoopSdkNpcSide; attack type with REACT), record (TweakDBID of a status or an attack), value (damage, influence radius, dilation), seconds (slow), point, vector (world space).

Limits: NCSDK_NPC_RATE_PER_S 20 requests per mod per second (bursts 2x; the owner counts per mod and partner), NCSDK_NPC_DATA_MAX 1024 bytes, NCSDK_NPC_PENDING_MAX 256 open general requests per mod at the owner, NCSDK_NPC_NEAR_M 150 m between our body and the NPC at the owner, NCSDK_NPC_SLOW_MAX_S 120 s, NCSDK_NPC_IMPULSE_MAX 1000.

Content a partner may not have

What NightCoop does by itself and how to use these: content-fallbacks.md.

kind of fallbackSet / contentHere (NCSDK_FALLBACK_*, script NightCoopSdkFallbackKind):

Names: 1..NCSDK_FALLBACK_NAME_MAX (128) bytes of printable ASCII. kind of peerHasKnownMod (NCSDK_KNOWN_MOD_*, script NightCoopSdkKnownModKind): RED4EXT 0, REDSCRIPT 1, CET 2, ARCHIVE 3, REDMOD 4, TWEAK 5, ASI 6.

Events and polling

The hooks of a C mod and the events of a script mod carry the same things.

Session events (NCSDK_EV_*, script NightCoopSdkSessionEvent):

Delivery:

• C with hooks: callbacks on the game thread, always from the SDK's own frame (the last of NightCoop's frame), never from inside a call of the table. A hook you leave NULL sends that kind of item to the poll queue instead.
• Poll queue: up to 1024 items per mod, the oldest are dropped (counted in the status line, see troubleshooting.md).
• Scripts: Listen(id, target, n"Function") makes NightCoop call target.Function(event) once per item on the game thread instead of queueing. The function takes exactly one ref<NightCoopSdkEvent>; Listen returns false otherwise. The target is held weakly: when it dies, items go back to the queue. Listen(id, null, n"") stops it.
• Every frame (scripts): ListenFrame(id, target, n"Function") makes NightCoop call target.Function(dt) on the game thread every frame while the player is in a world, after its own frame and your events (C has hooks.frame). The function takes exactly one Float and returns Void. Unlike a chain of DelaySystem callbacks it keeps running through loads of a save; the target is held weakly, so call it again from OnAttach. ListenFrame(id, null, n"") stops it.
• Registering in the middle of a session gives your mod the current picture: SESSION_START (if in a session), PEER_JOIN for each peer, PEER_WORLD_IN for each peer in our world, then PEER_MOD / PEER_NO_MOD as passports come.

NcSdkPolled (C): set size, optionally give a buffer (data, dataCap). It fills kind, peer, a, entity, ref, key, dataSize (the full size; the data is cut at dataCap), pose, request and effect (NPC events; key is then "<request>/<effect>", for the text form of PollEventText) and value.

Script event class NightCoopSdkEvent: kind, peer, a, key, removed, data (text; empty if not valid UTF-8), bytes, entity, ref, poseValid, head, leftHand, rightHand, aimOrigin, aimDir, request, effect, value.

Functions co-op relies on, keys

What they are for — do-not-hook.md.

C hooks

NcSdkHooks: size, context, then frame(ctx, dt), event, message, stateChanged, stateRequest, entityState, partnerPose, sharedSpawn, shutdown, npcRequest, npcResult, spawnLeader, reward, coopEvent, menuItem, voteResult, worldRequest. All optional. See getting-started-c.md for when each runs. stateRequest exists only in C.

The save, the co-op menu, votes and partners

The guest's entry into the host's world by save, your items in NightCoop's co-op menu, votes of mods, what a partner is doing, co-op events and asks to change the host's world. The script enums of this part are in the module NightCoop too (import NightCoop.*).

Flags they need

Reading a partner's state and co-op events need nothing. factKeepLocalList needs NCSDK_MOD_CHANGES_QUESTS, as factKeepLocal.

The guest's entry into the host's world by save

A guest who joins the host's world loads a save NightCoop builds from two: the world of the host's save (quest facts, the journal, scenes, the population, the world's script systems) and the guest's character (inventory, stats, perks, appearance, the character's script systems). See concepts.md.

Items in the co-op menu

Your items appear on NightCoop's own screen: Esc → «Co-op» → «Mods…» (also in the main menu). The list is the game's menu list, the same widgets NightCoop's items use (mouse, keyboard, gamepad, sounds).

Votes of mods

The host's copy of your mod asks every player of the host's world a question; they vote in NightCoop's choice window (the dialogue choice window: arrows, F or Enter, NumPad 1..8; who voted for what is written on the options, the title tells how far the vote is). The window shows the question only when no choice of the game and no vote of NightCoop is on screen; one vote at a time in a session. The host's voting mode decides («Choice voting: everyone / more than half» in «Extra settings» of the co-op menu); the host can apply its own choice by holding End, as for NightCoop's choices; NightCoop's voting time (when the host has one) applies too. Players without your mod vote as well — the decision is the session's.

Recipe: a convoy quest asks before it starts.

@if(ModuleExists("NightCoop"))
private func AskConvoy() -> Void {
  let ru: array<String>; ArrayPush(ru, "Едем"); ArrayPush(ru, "Не сейчас");
  let en: array<String>; ArrayPush(en, "Let's go"); ArrayPush(en, "Not now");
  NightCoopSdk.VoteStart("author.convoy", "start", "Начать конвой?", "Start the convoy?", ru, en);
}
// in the Listen function: if event.kind == 12 && Equals(event.key, "start") && event.a == 0 { StartConvoy(); }

What a player is doing

Co-op events

They come as session events (NCSDK_POLL_EVENT, script kind Session), a = the event, with value, entity, ref. A C mod with the hook coopEvent(ctx, &event) gets them there with all details (NcSdkCoopEvent); without it, event gets event and peer only. Partners count only while in our world.

NcSdkPolled.value and NightCoopSdkEvent.value carry the value; PollEventText has it as the ninth field.

Asking the host to change the world

The host leads the world's time and weather: a guest's own change is undone within seconds (the host's clock, weather_host). A mod asks instead — right flag NCSDK_MOD_USES_WORLD_ASK (1 << 23; script UsesWorldAsk, CET USES_WORLD_ASK).

Not in the list, on purpose: the pace of time — the game's TimeSystem has no setter of it for scripts (only SetGameTimeBySeconds/ByHMS and time dilation by a reason); mods that change it do so with data, which every player needs (NCSDK_MOD_NEEDED_BY_ALL); and the world's pause — it belongs to NightCoop's menu (the world stands when every player is in a menu).

Mods without code: the manifest

A mod made only of data (TweakXL records, ArchiveXL, quest phases) can tell NightCoop the same with a file <anything>.nightcoop next to it: manifest.md.