BUILD YOUR OWN GIG

FROM PYTHON TO NIGHT CITY

Three gigs have come out of this pipeline. Python generators write the quest graph, the scenes, the journal and the map pins as JSON. WolvenKit cooks the JSON into the game's binary formats (.questphase, .scene, .journal, .ent). Everything gets packed into a single archive, and ArchiveXL merges it into the game at launch. The scripts compile with redscript in the player's game.

The generators run dependency-free, and all generated output is committed, so a fresh clone builds without running anything. Every gotcha that cost an evening is written down so it costs you five minutes.

WHAT THE TOOLKIT CAN DO

UNDER THE HOOD

1. Map pins without shipping a single game file. One way to place a mod-added quest pin is to overwrite Night City's cooked mappin tables. You don't have to. ArchiveXL computes a pin's position from a node reference plus an offset, but the node has to be streamed in when the quest activates the pin, and quests activate pins while you're on the other side of the city. Night City has exactly three sectors the engine never unloads, holding 5,211 globally named nodes between them. Anchor to one of those and the pin just works:

2. Voiced dialogue needs no audio mod. A scene line carries one number, and the game resolves both the subtitle and the audio from it: the words come from a subtitle resource keyed by that number, the voice comes from a locVoiceoverMap keyed by the same one. ArchiveXL merges a mod's entries into both. Gendered V lines are handled by the engine, not by you:

3. A scene can put a body exactly where you are standing. Lip sync lands on whoever the scene says is speaking, so the scene has to own Johnny's body. For months the playbook here said a scene could not put that body in front of the player: the marker a scene stages an actor on "lands a few metres to one side", and its rotation is "not knowable". A whole architecture was built around that sentence. The speaker was buried under the floor for his voice, a second body was spawned by script, a workspot device lifted it into place, and a 40 m sweep ran six times a second to find it again. The sentence came from one playtest note about how a voice sounded, from an actor who was underground at the time. What it was hearing was the floor. Measured in five runs, the marker sits at V's exact position, carries V's rotation, and +Y is forward:

Every workaround above was unnecessary, and the T-pose two Nexus reporters described was a side effect of the workaround rather than of anything the engine forces. Deleting the lot is most of what version 1.2.0 is. A claim that forecloses an approach is worth measuring before it earns a "do not", because a wrong "impossible" costs whatever gets built on top of it, and nobody goes back to re-test it.

4. A video holocall from a contact you invented. A holocall with a live picture is not a video file. The game keeps a hidden set off the map, a "studio", with a camera, lights and a spot for the caller to stand on, and the phone renders whatever that camera sees. Issue the call from the quest graph rather than from script, because the graph's node is the only one carrying the field that aims the phone at the studio:

The caller has to be a contact you invented. Borrow the game's own Nix and his small-talk conversation takes the call over, so the player gets his default options instead of your scene, and cannot ring out at all. Someone also has to be standing on that spot for the camera to point at, and the game only draws a character in a scene while they are playing an animation. Standing is not one. Put them in a workspot on the scene's first frame or the phone shows an empty room, silently, with nothing in any log.

The lipsync itself ships no animation data at all. Each line borrows a vanilla lipsync animation of roughly the right length, which reads as real sync at conversational distance.

5. The code grid on a wall box you ship yourself. Breach protocol runs on an access point, and an access point is an ordinary device node you can put in a sector of your own. Which one you copy decides whether it works. A quest access point lifted out of the game gives a prompt reading "Install Software" that does nothing, because its saved state carries a personal-link interaction only its own quest ever finishes. Copy one of the street routers instead: their buffer holds the entity and nothing else, so the game builds the default state, which is the one every open-world router runs on. Two more things. The "Jack in" prompt has a volume positioned per appearance, so a box that offers no prompt facing into a room may offer one turned around: place it, then rotate it until the prompt shows. And the list of daemons lives on the controller's saved state, which a node with no saved state cannot carry, so name it from script:

6. A quest area drawn on the minimap. The dotted outline the game draws for its own "leave the area" objectives is not a special kind of pin. It is an ordinary quest map pin whose target happens to be a trigger area node, and the minimap draws the outline while that objective is tracked and the player is standing inside it. 638 of the game's own quest pins point at one. A mod can do the same, but ArchiveXL builds the outline only from a node that is an area shape node: a device node carrying a trigger component gives the pin a position and no outline, and a trigger node the loader can't find gives a marker at the world origin, which reads in game as a marker a kilometre away. It has to be a trigger area node, in one of your own sectors that is always loaded, named in the long form:

7. The whole site knows where you are, and so does the wanted system. NPCs placed by a community spawn with no particular attitude towards V. Making one hostile and aware of the player's position is the four calls the game makes on each MaxTac unit after it lands: the first two make V an enemy they can see, the third shares V's location, the fourth puts them in combat at once instead of waiting for a detection:

The wanted level is a request to the prevention system, the same one the game queues. Heat_0 turns it off again, at whatever place or objective you choose. The responders only know where the player is once one of them has a sighting, so a player who leaves the road can hide. Unless the mod reports the position for them every few seconds, which sets it as the last crime point and hands it to whoever answers, Militech in the Badlands and the NCPD in town:

Acceptable Loss runs all of it: the trace on the security-room door turns the compound, three stars land, and the hunt holds until the district boundary. The gig page has the same notes next to the gig.

WRITTEN FOR THE WIKI

The repo keeps what is specific to these gigs. The general how-to went to the community wiki, where other modders look first and can correct it. Five pages so far, written from scratch by nightcityriot and tested in game on 2.31, each one starting from something that broke while building a gig.

THE CYBERPUNK 2077 MODDING WIKI[OPEN]

EVERYTHING IS WRITTEN DOWN

The repo holds the reusable builders under tools/questkit/ (scenes, quest graphs, journal entries, map pins, voice, lipsync), the generator scripts, the shared redscript, and the complete source of all three gigs as working examples. The docs cover the fundamentals, how to start a new gig, and the register nobody else keeps: 103 things that cost hours each.

OPEN THE REPO ON GITHUB[FORK]

Bugs in a gig itself are best reported on Nexus; issues with the scripts and docs belong on GitHub. Want to see the result first? Play Acceptable Loss, Dead Ringer or Negative Balance.