WARNING : Mod support for Horizon's Gate is always a work in progress!

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 Horizon's Gate! This guide is not comprehensive, but should explain enough to start making most kinds of content for HG. Please feel free to make your own guides with more thorough detail!

First: there are two important folder locations for modding.
The Mods directory is at
X:\Users\Username\AppData\Roaming\BoatTactics\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\Horizon's Gate\Content
and is important for viewing examples of existing data formats.

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
    
  • allows certain other commands in build mode
    
  • 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 port1). gob puts you into Build mode immediately. Going to a zone that doesn't exist yet generates a brand new zone.
  
• z, bz, and sp 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\BoatTactics. 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 of 9.

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 New Effect to add a TriggerEffect 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 a trigger box to edit its trigger.
  
• Hold right-click on an effect text field for a mousewheel-able list of possible TriggerEffects.
  
• Not all TriggerEffects are safe to use or work correctly! Generally, only use TriggerEffects that have a tooltip explanation.
  
• Hold right-click on Element text fields for a mousewheel-able list of Elements.
  
• Some common TriggerEffects are:
  
  • travel_point handles most normal travel from zone to zone.
    
  • travel_leaveLocation is used to go from the current zone to the overworld.
    
  • 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 TriggerEffect can also be called via the console or via dialog specialEffects.

----------

To edit an Actor, middle-click them and it will bring up their properties window.

Additional 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 rotate an actor, hold them 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.
• Some actor properties do nothing, while others are very useful. Some important ones:
  
  • canDespawn, if true, lets the Actor's corpse disappear if the player leaves the zone.
    
  • 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 can be found in Horizon's Gate\Content\Data\ZoneData. 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 Horizon's Gate\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 Super Cool Beach right near Searth. If this file is in the Mods directory, any save that doesn't already have Super Cool Beach will automatically add one to the overworld!

NOTE: you can 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 base data will not affect it! The player now has their own version that will never be overwritten!

NOTE: please store Location or Zone data 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. With ZoneMerges you can even change Zones that the player has already been to.

To do this, edit your zoneID.txt file and make some changes:

• Change "[Zone]" to "[ZoneMerge]".
  
• Add three new properties under [ZoneMerge]:
  
  • "mergeWith", which specifies the ID of the zone to merge onto. (example: "mergeWith=eral;")
    
  • "X" specifies the X position to put the top left corner of your zone.
    
  • "Y" specifies the Y position to put the top left corner of your zone.
• You can also add an "fReq" property if you want to specify a formula requirement that must be calculated as greater than 0 for the ZoneMerge to apply.

You can also check out the example ZoneMerge in the ModSamples folder. It adds a small boat to the bottom left of port1 (Port Otype).

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).

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.

Once applied, the globalVar zoneID + "_merged" (ex:myModZone_merged) is set to 1 as a way to remember not to reapply the same merge ID to that save file. For example, when the sample ZoneMerge is applied, it sets "sampleMod_boatInPort1_merged" to 1.

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

The game's items are all stored at Horizon's Gate\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 Horizon's Gate\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 Iron 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 Warrior's Guard:


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
  
• adjacentAndSelf
  
• adjacentAndSelf+1
  
• adjacentAndSelf+2
  
• adjacentAndSelf+3
  
• allParty
  
• allActors
  
• allAllies
  
• allEnemies

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


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 that some files are named strangely (actions_knight.txt contains all the Warrior actions).

NOTE: 'duration' uses an odd 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 Horizon's Gate\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.

Actions and dialog do not support cloneFrom.

For detailed info on how to add custom dialog, check out this excellent in-depth guide by Radiatoryang:
https://steamproxy.net/sharedfiles/filedetails/?id=2066008133
You can also create TerrainTypes of your own. I recommend using the in-game TerrainType editor, saving in that editor, then copying your new TerrainType out of Horizon's Gate\Content\Data\SystemData\Definitions\terrain\terrain.txt and into your own 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. They do NOT support standard use of parentheses.

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:

One oddity of 'd' is that you can pass in a number in parentheses, such as with "d:fireDmg0(2)". This causes the passed in number to take the place of 'x'.

In the case of fireDmg0(2):
becomes

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 Horizon's Gate, go the main menu, and select Mods > Create > Upload New.
   
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, this mod's ID is 2127597667:
http://steamproxy.net/sharedfiles/filedetails/?id=2127597667

NOTE: 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.

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

------------------------

Please feel free to post questions in the comments or send questions to radcodex at gmail. To learn more about modding, you can visit the official Horizon's Gate discord (more info here) and check out the #mod-creation channel.

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. When you specify a shape, use the number, such as "shape=2;".

Here is a complete list of all Elements as of v1.1.1, some with notes on their function.
Some Elements are unused, despite having comments on them.

Here is a complete list of formula calculations as of v1.5.88.

Here is a complete list of math ("m:") calculations that can be done by Formulas as of v1.5.88.

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


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").

This is a list of all hardcoded formulas used by Actions, AvAffecters, and many other things as of v1.4.5. You can overwrite these by matching their ID in your FormulaGlobal definitions.

This lists all hardcoded Support Abilities. NOTE: THEY ARE NOT IN THE SAME FORMAT THAT MOD SUPPORT ABILITIES SHOULD BE. This is merely a list for reference sake; if you copy paste one of them into a mod file it will crash.

Their Actions are stored separately in actions_support.txt.