Concepts

Session, host and guests

A session is a group of players connected through NightCoop. One of them is the host; the others are guests. Every player has a peer number: the host is always 0 (NCSDK_PEER_HOST), LocalPeer() / where().localPeer is your own number, -1 (NCSDK_PEER_NONE) out of a session.

• "In a session" means connected. The host is in a session as soon as it hosts, even with no guests yet.
• Out of a session the game is plain single-player. The SDK still works then: your mod registers, shared state is stored locally, channels reach nobody. Write the mod so that this case needs no special code.
• Peer numbers belong to one session. Do not store them in a save file or use them as a player's identity.

The host's game is the world

The host's game runs the world: time, weather, NPCs, quests, the population. Guests see it through NightCoop. The consequence for mods:

If a guest changes the world locally, that guest's game diverges from everybody else's.

So a mod that changes the world must do it on the host and let guests ask: by a channel message or by writing shared state (the host decides, see below). A mod that changes only its own player (looks, HUD, controls, camera) needs no host at all. Register that with NCSDK_MOD_LOCAL_ONLY.

In the host's world

A guest is not always in the host's world: it may be in the main menu, loading, or in its own campaign. Two checks:

Events PEER_WORLD_IN / PEER_WORLD_OUT tell when a partner enters or leaves your world. Anything that involves a partner's entity (a mirror of their car, their body) makes sense only while both of you are in the host's world.

Ownership: who leads what

Every player leads (owns):

• their own player character;
• the vehicle they drive;
• the NPCs NightCoop handed to them (and NPCs given to them later).

On every other machine the same thing exists as a mirror or copy: a local entity that follows the owner's data. You can read it, but the owner decides what it does. Two rules:

1. Change only what is yours. For anything else, ask the owner (a channel message to that peer).
2. Ask first which it is: entityIsMine(entity) returns 1 (yours), 0 (a partner's, yours is a mirror or copy) or NCSDK_E_UNKNOWN (NightCoop does not sync it, so it is purely local and therefore yours).

An entity you cannot name across machines (an EntityID is local) is named by a network reference (NcSdkNetRef: kind, owner, id), the same on every machine. entityRef turns a local entity into a reference, entityOfRef turns a reference into the local entity (mirror, copy or your own), or 0 if it is not here now (not streamed, not spawned yet). In scripts the reference is packed into one Uint64: kind 8 bits | owner 24 bits | id 32 bits.

References and local EntityIDs are not permanent. A mirror can be destroyed and created again under a new EntityID; an NPC can pass to another owner. Do not keep an EntityID of a partner's entity as a permanent handle: ask entityOfRef when you need it, or let NightCoop push your data to the current mirror (entity state, see api.md).

Where mod data goes

A mod has three ways to put data on other machines. Pick by what the data is:

The mod passport and the protocol

When a player appears in the session, every player tells every other the list of their registered mods: id, version, protocol and flags (the passport). It is sent again whenever a mod registers or unregisters.

• Mod data travels only between players who registered the same id with the same protocol. A partner without your mod, or with a different protocol number, receives nothing and cannot send you anything. Nothing is sent to them, and nothing breaks.
• peerHasMod(peer) answers 1 (yes), 0 (no, or another protocol) or NCSDK_E_STATE (not known yet: the exchange with that player is not over). Events PEER_MOD / PEER_NO_MOD announce the answer.
• Raise your protocol when the meaning of your data changes in a way old versions cannot read. Players on different numbers then simply do not talk to each other, which is better than misreading.
• If you register with NCSDK_MOD_NEEDED_BY_ALL and a partner lacks the mod (or has another protocol), both players get a short note on screen, once per partner and mod, and a log line. Entry to the session is never refused.

Why the host decides shared state

Shared state has one writer of record: the host. When the host sets a key, it stores it, tells itself and sends it to all peers that have the mod. When a guest sets a key, the guest only sends a request; the host's mod may refuse it (stateRequest hook in C; scripts accept everything), and only the host's answer changes the value, for everybody including the guest. This is also why two players cannot disagree about the value for long.

Flag NCSDK_MOD_HOST_AUTHORITY documents the same decision for your whole mod: its world changes come from the host, guests ask the host.

The guest's save in the host's world

A guest joins the host's world by a save NightCoop builds on the guest's machine from two saves: 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, wardrobe, and every other script system. When the session ends, the way back builds the guest's campaign the other way round: its own world, the character of the session.

For a mod this means:

• A ScriptableSystem of your mod is the character's by default: the guest brings their own state (needs, addictions, equipment sets, a wardrobe). A system that keeps the world of your mod (its NPCs, a gig board, an economy, events of the world) can say so: scriptableScope(mod, class, NCSDK_SCOPE_WORLD) — the guest takes the host's state of it, and the way home brings back the campaign's own.
• A quest fact your mod marked with factKeepLocal keeps the guest's own value at the entry (and the session's value at the way home). Mark your facts right after registering: the word counts at the moment of the entry.
• Items with the quest flag that are not equipment go aside for the session at the first entry (the host's quest graph must not see quest items of another campaign) and come back home with the guest.
• Entities a mod keeps in the save (Codeware's persistent spawns) are the world's: the host's.

What a partner is doing, and co-op events

partnerState answers for any player of the session (and for yourself): in our world or where, downed, in combat, in a vehicle (and which one — a network reference you can turn into your own entity), in a scene, in a menu, health and level. Co-op events say when it changes — a partner fell or got up, every player is down (the co-op death: nobody dies alone in a session, the host loads its last save), a partner got into or out of a vehicle, an NPC was killed by a player (and by whom), every player is in a menu (the world stands), the host saved or loaded, the host skipped time. They come from what NightCoop already knows; reading needs no flag.

NightCoop's own interface for mods

A mod can put its own items into NightCoop's co-op menu («Mods…») and ask every player a question in NightCoop's voting window. A vote of a mod decides like NightCoop's choices: by the host's voting mode (everyone / more than half), the host can apply its choice by holding End. Each player sees the texts in their own language (give Russian and English), never the host's text in another language.

Events of libraries and of the SDK