The boilerplate mod

Your first mod is three small files. A real mod quickly needs much more: scenes that start on their own, actions at places and on people, a quest, a settings page, and above all scenes the town's NPCs can play too. ul_Boilerplate is all of that, wired together and working, with every line of text left as a placeholder.

It ships with the game in Content/Modules/_Templates/ul_Boilerplate/. The game never loads it: only the folders directly under Content/Modules/ and Mods/ are mods, and _Templates is not one. It is also in the official mods repository, under _Templates/.

#Start your mod from it

1. Copy ul_Boilerplate into Mods/ and rename the copy, yourname_mymod for example. ul_ is reserved for the official mods.
2. Replace the names inside it. In this order, case-sensitive:

From PowerShell, inside the copied folder:

text$pairs = @(@('ul_Boilerplate','yourname_mymod'), @('Boilerplate','MyMod'), @('ul_bp','ymm'), @('UlBp','Ymm'), @('ulBp','ymm'))
Get-ChildItem -Recurse -File | Where-Object { $_.Extension -ne '.png' } | ForEach-Object {
  $t = [IO.File]::ReadAllText($_.FullName)
  foreach ($p in $pairs) { $t = $t.Replace($p[0], $p[1]) }
  [IO.File]::WriteAllText($_.FullName, $t)
}
Get-ChildItem -Recurse | Sort-Object { $_.FullName.Length } -Descending | ForEach-Object {
  $n = $_.Name; foreach ($p in $pairs) { $n = $n.Replace($p[0], $p[1]) }
  if ($n -ne $_.Name) { Rename-Item -LiteralPath $_.FullName -NewName $n }
}

3. Fill in the .ulmod file (Anatomy of a mod) and replace thumbnail.png.
4. Search the folder for PLACEHOLDER and [PH]: every hit is text for you to write. [PH] marks choice labels, which the game draws as petals around the scene: keep yours under about 22 characters and put the detail in the option's tooltip (Choices).
5. Delete what you do not need. A scene can go as long as nothing names it any more: its .ulsocial entry, the SCENE_ALWAYS of its action.
6. Remove the [TEST] button of the Mods page before you publish.

#What is in it

Every scene offers at least three answers at its main choice, and most open a second choice. Every file explains itself in its comments.

#One scene for the player and for NPCs

The town's NPCs play the same scene files as the player, through the declarations of a .ulsocial file (NPC life). They do it in a separate, smaller API, and a call that API does not have refuses the whole NPC scene: nothing it did is kept. The boilerplate's scenes follow these rules:

• Branch before player-only calls. Game:isNpcSimulation() (the boilerplate's Boilerplate.npc(Game)) is true in an NPC scene. Check it before Game:Log, faceEachOther, startQuest, setActorAlias, Outcomes, Agenda, Events, Memory, addBuff, the camera or the HUD. Even Game:Log refuses an NPC scene.
• Who is who. Player is the NPC who runs the scene; Actor is the other NPC ("target": "nearby") or nobody ("self"). rapportwithplayer on Actor is what Actor thinks of that NPC.
• Nobody is created. In an NPC scene Game:generatePerson() takes no arguments: the first call returns Actor, each next one someone else already at the place, as many times as the scene's maximumParticipants allows. When nobody fits, the scene is refused, which only means it does not happen this time.
• Text. <Actor.name> tokens are not filled in for NPCs, and Actor:GetToken only knows name, he, him and his. Build shared lines with :name() and GetGenderedWord. Narration is the player's first person ("I…"), so give NPCs a third-person line or none.
• Every option an NPC may see needs a rule in the .ulsocial choices. Give each choice point of a scene its own range of indices (0-3, 10-12, 20-23) and "point": 0 (any choice point) stays unambiguous.
• Libraries. An NPC scene only has the libraries its entry lists. A library listed there must only define things: Events:on is ignored there, but Events:handler refuses the scene, so keep event code in a file of its own.
• Actions NPCs may take have an NPC block and none of WHERE = { "interaction" }, WHO_LUA, AVAILABLE, END_PARTY, OUTDOOR, WEATHER, a BUFF effect, an Interacting: or rapportwithplayer effect. Their SCENE_ALWAYS must be declared in a .ulsocial. Interactions stay the player's: NPCs reach the same scene through the .ulsocial instead, as ul_bp_talk and ul_bp_group do.
• Scenes under a Quests/ folder are player-only.

#Test it

• From the game's source repository, python Tools/ModDocs/validate_mod.py <your mod folder> checks every API call, id and venue tag against the game. It is also what to paste back to an assistant (Modding with Claude): the boilerplate is a good first file to give one.
• -WorldMapScene=ul_bp_encounter runs a scene at startup (Testing). A scene started on purpose like this has Game:ForcedTrigger() true, which the encounter uses to skip its dice.
• The Mods panel page has a [TEST] button that plays the encounter.