WARNING : Mods are generally safe to install and uninstall, but it is entirely possible to corrupt your game data or save data by creating or installing mods! In these instances, you may be forced to reinstall the game! Back up your save files, and mod at your own risk!

Welcome to a brief guide to modding Kingsvein! This guide is still a work in progress and is not comprehensive, but should explain enough to start making most kinds of content for Kingsvein.

To learn even more about modding, you can visit the official Rad Codex discord (more info here) and check out the #mod-creation channel.

First: there are two important folder locations for modding.
The Mods directory is at
X:\Users\Username\AppData\Roaming\Kingsvein\Mods
and can be easily accessed by pressing the small folder button in the top left of the Save/Load menu. When making a new mod, make a new folder here and put your files in it.

The Game Data is stored at
X:\Program Files (x86)\Steam\SteamApps\common\Kingsvein\Content
and is important for viewing examples of existing data formats. You can easily open this directory by right-clicking Kingsvein in Steam and selecting Manage > Browse Local Files.

By pressing "Shift" + "~" in-game, you can bring up the Console.

Some important console commands:

• h lists commands or gives more info on them.
  
• dm toggles Debug Mode, which:
  • allows you to bring up the console with just "~"
    
  • allows you to hold right-click on character stats, then mousewheel to alter them
    
  • causes the B key to toggle Build mode at any time
    
  • automatically refreshes mod files when you refocus the window
    
  • enables a warning system for common typos in mod files
• b enters Build mode, allowing terrain editing, item placement, etc.
  
• go and gob sends you to the specified zone (ex: go zSE1). gob puts you into Build mode immediately. Going to a zone that doesn't exist yet generates a brand new zone.
  
• z shows a list of zone data. They do not list zones in the Mods folder.

To permanently enable Debug Mode, open config.ini, found in X:\Users\Username\AppData\Roaming\Kingsvein. Change debugMode=False; to debugMode=True;.

Enter build mode with the console command 'b'.

In build mode, you can view and edit the zone, actors, and even terrain types. Use WASD to pan the camera.


The left panel creates Items or Actors.

• Click the tabs at the top to view different categories.
  
• Mousewheel to scroll the list of items or actors.
  
• Left click an item to create 1, or right-click to create a stack.

The right panel edits the zone and shows TerrainTypes.

• brings up a list of shortcuts and hotkeys when hovered.
  
• The Zone's ID can be edited in the text field at the top.
  
• Most buttons are self-explanatory if you hover them and read the tooltip.
  
• Below these buttons are the TerrainTypes.
  
  • Left-click or right-click to assign a TerrainType to that type of click. Click the zone to place that terrain type.
    
  • Mousewheel to scroll the list of TerrainTypes.
    
  • Middle-click a TerrainType to view or edit the TerrainType's properties.
• opens the Zone Settings Window.
  
  • From here you can edit many values of the zone, such as palettes, darknessColor, etc.
    
  • Hold Right-click on palette text fields to view a mousewheel-able list of options.
    
  • Hold Right-click on color text fields to bring up a mousewheel-able color picker.
• saves the current zone to Game Data. Be careful not to overwrite your work!

Press T to toggle Trigger mode. This allows you to place event triggers in the zone.

• Press New Trigger to create a new Trigger, or + Task to add a Task to the currently edited trigger.
  
• Hold left-click on the zone to set the trigger box. Right-click to add additional boxes for the same trigger. Middle-click to remove additional boxes.
  
• Left click any trigger box to edit its trigger.
  
• Hold right-click on the effectID text field for a mousewheel-able list of possible Tasks.
  
• Hold right-click on the Triggered by text field for a mousewheel-able list of possible Elements.
  
• Triggered by can also take multiple elements. (Example: "physical, ruin, fire")
  
• Some common Tasks are:
  
  • travel_point handles most normal travel from zone to zone.
    
  • fx plays an fx or sound at the specified spot.
    
  • setGlobalVar sets a variable that is stored in the player's save.
    
  • spawn is a complicated effect, but is used to create actors or groups of actors.
    
  • enterCombat forces combat start in the specified area.
• Note: any Task can also be called via the console, dialog, or actions.

----------

To edit an Actor, middle-click them and it will bring up their properties window.
Notes on editing Actors:

• If debugMode is on, you can right-click a stat and mousewheel to alter its value.
  
• If debugMode is on, you can alter hostile/neutral by clicking the red or green gem in the character stats window. Right-click adds them to your party.
  
• To make an actor ride another actor, place them on the actor. (This is how Possessed have Wisp Nodes added to them.)
  
• To rotate an actor 90 degrees, pick them up and press 'R'.
  
• To change an actor's class, hover them and press 'C'.
  
• To edit an actor's appearance, hover them and press 'E'.
  
  • Left-click the arrows to select from options available to the player.
    
  • Right-click the arrows to select from all options.
    
  • The bottom text field is a sprite selector for bodyParts. Hold right-click and mousewheel to select a part to edit.
• Most actor properties do nothing or are very glitchy to edit directly. But others are very useful. Some important ones:
  
  • dialogNodeID specifies what DialogNode to use when the Actor is spoken to.
    
  • ai_lua is which .lua script to use for AI. "idle" is the proper script for almost all NPCs.
    
  • aggressiveness affects positioning in combat. High aggression (1+) makes the Actor move as close as possible instead of maintaining attack distance.
    
  • bravery affects likelihood of the AI fleeing in combat.
    
  • intelligence affects max time the AI can spend thinking, and how easy it is for them to reach a 'good enough' action and stop thinking.

Now that you know how to edit a Zone using Build mode, let's set it up so other people can visit it.

First, save your zone with in Build mode. Now your zone data will be found in Kingsvein\Content\Data\ZoneData. You can open this using the folder button in the top right of the build menu. Find zoneID.txt and zoneID.png (where zoneID is your zone's ID.) Copy these files, create a new folder in the Mods directory, and put the files there.

Now a player can visit your zones using travel triggers or via the console. But let's make it so they can access the zone from the overworld. To do this, we need to make a Location.

Take a look at the game's normal Location data at Kingsvein\Content\SystemSaves\defaultLocations.txt. This is the format we want to use to define our new Location.

In your folder in the Mods directory, create a new text file, and put a new [Location] in it by mimicking the format shown in defaultLocations.txt.

Here's an example:

This example creates a Cool Dungeon on the overworld map. If this file is in the Mods directory, any save that doesn't already have Cool Dungeon will automatically add one to the overworld!

NOTE: you can also override the game's default Locations or Zones by putting your own versions in the Mods directory and using the same ID. The game will always check Mods FIRST when loading Zones.

NOTE: after the first time a Location is created in a save, changing the data will not affect it! The player now has their own version that will never be overwritten!

NOTE: please store Location or Zone data in their own text files, separate from other data types, such as [ItemType] or [ActorType]. If the game detects a [Location] or [Zone] in a text file, it will not load that file on startup, and instead wait until the appropriate time.

You can also apply the contents of a Zone directly onto another Zone. This is mostly useful if you want to make changes to the overworld, but you can use it on any zone.

To do this, make a new text file with a unique name. In this file, make a "[ZoneMerge]".
Do NOT put anything else in this file! Here's an example:

The properties are:

• "filename", which is the name of the file.
  
• "mergeWith", which is the ID of the zone to merge onto. (example: "mergeWith=zSE1;")
  
• "mergeZone", which is the ID of the zone that you are applying on top of that zone.
  
• "X" is the X position to put the top left corner of your zone.
  
• "Y" is the Y position to put the top left corner of your zone.
  
• "fReq" is an optional property if you want to specify a formula requirement that must be calculated as greater than 0 for the ZoneMerge to apply.

Note that ZoneMerges apply once for any save that enters the zone, even saves that have already been in that zone. The ZoneMerge is applied the next time the player enters the zone (not including loading a save).

Once applied, the globalVar zoneID + "_merged" (ex:myModZone_merged) is set to 1 as a way for the game to remember not to reapply the same merge ID to that save file.

NOTE: ZoneMerges overwrite existing items! Be careful that it doesn't overwrite important things.

NOTE: ZoneMerges MUST be larger than 1x1, or the game will assume the file is corrupted.

You can create your own items, or override the normal items of the game.

The game's items are all stored at Kingsvein\Content\Data\SystemData\Definitions\items. Take a look at these files to get an idea of the formatting.

Now, take a look at the example item at Kingsvein\Content\ModSamples\items_mod1.txt. This example creates a new item that uses its own texture. Copy "items_mod1.txt" and "items_mod1.png" to a new folder in the Mods directory so you can access this item in-game using Build mode.

To override an existing item, set your item's ID to the existing item's ID. Additionally, if you'd like to retain all original properties of the item except for those you alter, you can use "cloneFrom".

As an example:

This example changes the color of all Ore Mail to blue, without changing anything else about it. (cloneFrom also allows multiple mods to 'stack' if they both modify the same item.)

You can create Actions that are used by Classes, Items, ActorTypes, or in Reactions on equipment, support abilities, and actor types.

Let's take a look at an example Action - the Knight's Brave:


The [Action] defines all the important properties such as name, description, XPcosts, special properties, etc.

[ActionAoE] is the area of effect that shows up for the player to select. In this case, it highlights the caster and adjacent tiles.

Each [AvAffecter] (there can be as many as you want) applies an effect. The [AvAffecterAoE] is which tiles (centered on the ActionAoE tile selected) to apply the effect to.

In this case, both AoEs use cloneFrom to use common area of effects. Predefined AoEs that you can cloneFrom include:

• oneTile
  
• adjacent
  
• adjacent+1
  
• adjacent+2
  
• adjacent+3 ... + 9
  
• adjacentAndSelf
  
• adjacentAndSelf+1
  
• adjacentAndSelf+2
  
• adjacentAndSelf+3 ... +9
  
• allParty
  
• allActors
  
• allAllies
  
• allEnemies

Anyway, for now let's edit Brave so it has a 50% chance to grant +2 Magic Attack for 2 turns. To do so, let's add a new [AvAffecter] and [AvAffecterAoE]. That would look like this:


NOTE: You'll notice that chance isn't just "50", it's "50 - 100 * m:tIsRider". m:tIsRider gives a value of 1 if the target is riding a mount. Because buffs in Kingsvein always affect only the mount and NOT the rider, we use "-100* m:tIsRider" to make this ability unable to hit the rider.

NOTE: This effect lasts two turns, but duration is 60. In Kingsvein, a turn is 30 tics long. So a 2-turn effect should be 60.



Take a look at the other existing actions to get a better understanding for them! They can be found under Data\SystemData\Definitions\actions.

NOTE: 'duration' can also use a special system for indefinite or turn-based timers. The way to do those effects is:
-1 = indefinite.
-2 = instant + permanent.
-3 = until start of next turn.
-4 = until end of next (including current) turn.
-5 = until end of next 2 turns. (use this for abilities that you want to last until end of next turn.)
-6 = until end of next 3 turns, etc...

You can create ActorTypes, ActorClasses, and dialog in the same way as with ItemType. Look in Kingsvein\Content\Data\SystemData\Definitions\actors\ to find the game's normal types and classes.

Create your own by following the format in the original data - or override existing types by using the same ID.

You can also create TerrainTypes of your own by using the in-game TerrainType editor. Once you finish making your new TerrainType in the editor, click the Clipboard button to put the TerrainType's data into your clipboard. Then paste your new TerrainType into your mod file.

Formulas are used in Actions, AvAffecters, Triggers, dialog and more. They allow calculating numbers on the fly and have a unique syntax.

Formulas support normal math operations like +, -, /, *, and use standard order of operation rules.

Here are some examples of valid formulas:

In addition to normal numbers, formulas can use a selection of hardcoded calculations that are in the format 'prefix:value'.

Here are the most commonly used calculations:

Images and sound effects will override eachother if they have the same filename. Please use unique filenames to ensure that your files are not overridden by other mods.

Sound effects and music only support .wav format. Music filenames MUST start with "Song-".

Uploading to Steam Workshop is a very simple process. And don't worry about doing it perfectly the first time - all mod uploads are set to Private by default!

1. Put all your mod files into a folder in the local Mods directory.
   
2. Add a 512x512 .png into that folder with the same name as the folder. (Example: MyMod/MyMod.png)
   
3. Open Kingsvein, go the main menu, select Mods, and click the Upload button on your mod.
   
4. Enter the name of your mod folder.
   
5. Enter tags to describe your mod, such as Gameplay, Items, Location, etc. Each tag should be separated by commas.
   
6. Let the upload complete, then click the checkmark to view your mod online!
   
7. Edit your mod's description, images, and so on, then set its Visiblity to Public when you're ready.

If you need to edit the contents, preview image, or tags of your mod, you can do so with the other in-game options 'Edit Content' and 'Edit Tags'. You'll have to type in the ID # of your mod to do so.

The ID # is the long number found in your mod's URL. For example, in the Krakenslayer mod: https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=3156939551
The ID # would be 3156939551.

This is a list of all data types that can be created or edited with a text file.

There are also some types not listed that you don't edit directly (for example, Zones contain Actors, Items, and Triggers, but you would create them via the in-game build mode instead of typing them out).

Notes:

• In addition to these types, mods can also replace textures, sounds, and music.
  
• AoE stands for Area of Effect.
  
• Reactions are what happens when the type is affected by an Element or ActorValue.
  
• AoE, Effect, Reaction, and Light each use standardized formats across types. (Ex: ItemEffect and SupportAbilityEffect use the same format.)

When creating an Area of Effect, you can choose a specific shape from these options. It's best to specify the name (shape=line;) but the number also works (shape=2;).

If you are using plus, you can make it a square by adding 0.5 to the maxRange. (Ex: 1.5 reaches all 8 squares surrounding the center.)

Here is a complete list of all Elements as of v1.062, some with notes on their function. Elements are used to cause Reactions on items, actors, and terrain.

Some Elements are unused, despite not being commented as such.

In addition to normal syntax, formulas can have extra prefixes that modify a single value. This is a complete list as of v1.062


NOTE: Prefixes can stack. "swapCasterTarget:abs:moreThan:3:t:PhysAtk" is valid syntax.

NOTE: you can only apply the prefix to a single value- "lessThan:5:c:PhysAtk" works, but "lessThan:5:c:PhysAtk - 2" is going to return a negative number.

In order to have your prefix apply to a more complicated formula, you may need to make a FormulaGlobal and refer to it using "d:" (such as something like "lessThan:5:d:myPhysCalc").

Universally accessible Global Formulas are defined throughout various files as [FormulaGlobal]s and used in Actions, items, triggers, and other things. Some of them are hardcoded instead and are listed here.

They are also frequently modified by other [FormulaGlobal]s - for example, 'supportAbilWpnDmgMult' is modified in c_supports.txt to add certain support abilities' damage multipliers to it.

That makes this list rather incomplete for understanding the actual formula, but here is a list of all the hardcoded formulas regardless:

These old formulas are completely unused: