▶ ICEPICK // OPEN SOURCE · MIT
BUILD YOUR OWN GIG
Everything used to build a working quest mod for Cyberpunk 2077, open on GitHub: the tools, the research notes, and the full source of a shipped side quest to learn from.
// PYTHON GENERATORS · WOLVENKIT · ARCHIVEXL · REDSCRIPT · NO GAME FILES SHIPPED
FROM PYTHON TO NIGHT CITY
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
CAPABILITY 01
Vanilla-grade map pins
Quest pins that route the player there, show the gig icon, and behave exactly like the game's, without shipping a single game file.
CAPABILITY 02
Spawn Johnny and make him glitch
Have Johnny materialize beside the player anywhere in the city, deliver lipsynced lines, and glitch back out.
CAPABILITY 03
Scenes with dialogue and lipsync
Subtitled conversations with working audio and lipsync. No audio framework, no extra dependencies.
CAPABILITY 04
Phone calls that behave
Calls that ring like the game's own: they wait out fast travel, survive reloads, and try again if you miss them.
CAPABILITY 05
Journal, objectives, payout
A gig that appears in the journal, tracks objectives step by step, and pays out on completion. Indistinguishable from vanilla.
CAPABILITY 06
Borrow the game's own cast
Pull vanilla NPCs like Mama Welles into your scenes and pause their default chatter while your gig talks, or spawn a custom NPC of your own.
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:
"offset": { "X": 12.4, "Y": -3.1, "Z": 0.5 }
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:
+--> locVoiceoverMap -> the .wem that plays
3. Johnny is two jobs, not one. Lip sync lands on whoever the scene says is speaking, so the scene has to own his body. But a scene can't put him in front of you when you could be anywhere in the city, so a script places him, by spawning an invisible device and playing a workspot through it. The catch that cost an evening: the workspot plays through the device, so the device's rotation wins over the puppet's. Forget one line and he delivers every line with his back to you:
dev.orientation = EulerAngles.ToQuat(angles); // <- this one
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.
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 Negative Balance as a working example. The docs cover the fundamentals, how to start a new gig, and the register nobody else keeps: 28 things that cost hours each.
docs/orientation.md
Gig fundamentals: what a gig is made of and how the pieces relate. Read this first.
docs/new-gig.md
Creating a new quest from scratch with the questkit builders.
The gotcha register
Map pins, scenes with lipsync, computer UI, journal systems: the reference notes on how each subsystem actually behaves, including the failures.
mods/gig-01-negative-balance/
The complete source of a shipped quest mod. Read it, take what's useful, build your own gig with it, or tell us what we got wrong.
Bugs in the gig itself are best reported on Nexus; issues with the scripts and docs belong on GitHub. Want to see the result first? Play Negative Balance.