Hello, everyone!

My name is João Caju and I can't code even to save own my life.

But, over the last months I learned a lot about how to code on Wyrmsun and would like to share my experience with you - so you too can experience the joy of creating your own digital thingies and become an aspiring Code Wizard.

If you have any question or suggestion, be free to message me through Steam or on Wyrmsun Discord (https://discord.gg/eXfGpr96Bj).

---

• Topic introduction

That's an outstanding question, aspiring Code Wizard!

Both Custom Heroes and Custom Characters are hero units that will function exactly the same in-gamem since they share the same "persistent features" (meaning levels, items and skills will carry over) and both .

However, they have some differences in their creation process, which affect how much each one can be customized. Bellow, you can check which one you prefer.

---

• Custom heroes: "Your first own hero"

Custom Heroes can be created directly in game, through a special menu option located on the "Single Player" tab. For that reason, they are what most players will see first.

While they are the easiest to made, custom heroes are more difficult and limited to code, as they use a coding language is slowly being dropped from the game ("Lua").

Unfortunately, this also means they can't be easily shared as Steam Mods. At the very least, you can still copy your custom hero files and share them in the old-fashioned way as a normal computer file (via a pendrive and etc.) and place them on the correct folders.

While the menu gives you plenty of options for a custom hero, many more are avaliable if you change the code directly. For instance, you can switch an existing name, unit type, or civilization to otherwise unacessible ones.

This is a cool way of having a custom gnome or kobold hero! Be aware that changing a hero faction or civilization might alter how they appear and are able to be recruited.

Also, always keep a backup version of any hero you intend to alter!

Tip: You can check and change your Custom Heroes' code at the folder <Steam\steamapps\common\Wyrmsun\wyr\heroes\custom>.

---

• Custom characters: "Your imagination is the limit"

Custom Characters can only be created through coding. While that may be more difficult than using a menu, they use a simpler coding language that is easier to understand than "Lua".

This is the exact same process used to create the default hero units (Ex. Durin and Modsognir).That is why those heroes are refered simply as "characters" in the game files.

For this reason, they have a lot more in-depth customization. For instance, you can make your custom heroes have a custom portrait; spawn with items with unique names or magical effects; or have a much more complex lore entry in the Encyclopedia.

On the image, you can see an example of a Custom Character's ("Onfim) encyclopedia entry. It has some unusual and custom elements - like an unit type not normally avaliable to custom heroes ("Varagian Warrior") and a custom personality trait ("Creative").

Something unique to custom characters is that they can be easily transformed into a Mod by using the tool available at the Wyrmsun launcher! - and we're going to better talk about this on the next topic.

Tip: Check how baseline Characters are coded by looking the files located on <Steam\steamapps\common\Wyrmsun\data\characters>.

---

• Topic conclusion

Let's recap: If you want to create your own new hero you can choose do it through the in-game menu (and alter the hero files after, to better suit you) ("Custom Hero method"). Or you can do it by directly coding a character and setting it as a Mod folder, ready to be shared ("Custom Character method").

Either method is valid, and you should always pick the one you are most confortable with.

For the rest of this guide, I will focus on explaining the Custom Character method

---

• Topic introduction

Before you can code your Custom Character, you need to create the folders that will store it - and put them on a place the game can actually read them.

To do this, you will need to locate some folders on your computer and create even more folders some notepads with specific names.

---

• Creating your Mod folder

First of all, you need to open the "DOCUMENTS" folder of your computer (or equivalent). Normally, you can find it by clicking the mini computer shortcut on your desktop.

On "DOCUMENTS", you will find another folder called "WYRMSUN" (which is different from the one located inside Steam folders). When you open it, you will find a sub-folder called "MODULES" folder - this the place used by the game to store mods.

On "MODULES", create another folder and name it however you like. For this guide purposes, we will name it "YOUR_MOD".

Inside the "YOUR_MOD" folder, create a NOTEPAD named "MODULE". Then, open the notepad and write the actual name you want to use for your Mod, like this: <name = "Your Mod">.

Then, add a folder named "DATA" to your "YOUR_MOD_FOLDER". Open "DATA" and create another folder called "CHARACTERS" - this is where all custom characters information will be stored.

Lastilly, open the "CHARACTERS" folder and create a Notepad with your hero's name. That notepad is where we will start to code!

Tip: The entire path should look something like this: <ThisPC / Documents / Wyrmsun / Modules / YOUR_MOD_FOLDER / Data / Characters / YOUR_CHARACTER_NOTEPAD>.

---

• Topic conclusion

In short:

1. Open your "DOCUMENTS" folder.
   
2. Open "WYRMSUN" folder.
   
3. Open "MODULES" folder.
   
4. Create a folder inside "MODULES" with a name that suits you (could be just some version of your mod's name).
   
5. Inside "YOUR_MOD_FOLDER", create a notepad.
   
6. Rename the notepad to "MODULE" and write your mod's name like this <name = "Your Mod">;
   
7. Exit the notepad and create a folder called "DATA".
   
8. Inside "DATA", create a folder called "CHARACTERS".
   
9. Finally, create a notepad inside "CHARACTERS" and name it as you like (could be a version of your hero's name).

Phew! That's a handful... We will start next topic by opening that last notepad file to write the code of our Custom Character.

---

• Topic introduction

We already learned how to create and name a folder contaning our Custom Character. Now, let's get to write the code that will actually bring our character to life!

On this topic, I will share a basic template that you can just copy and paste on the Notepad inside the Characters folder.

---

• Basic template for Custom Characters

The final result should look like this:

---

• Topic Conclusion

The text above was just a basic template of the most essential information required to create a character.

Read it carefully and you will learn a lot just by modifying it with other information you find on the game files.

On the next topic, we will learn more in-depth what every single one of those coding things do - and more!

---

• Topic introduction

Over this topic and the next, I will show you a detailed template for your Custom Character, which you can use on your custom character notepad to start coding.

I will also explain what the following lines of code do (to the best of my knowledge):

1. Name.
   
2. Icon.
   
3. Unit Type.
   
4. Variation.
   
5. Forbidden Upgrades.
   
6. Civilization.
   
7. Default Faction.
   
8. Gender.
   
9. Deities.

---

• Detailed Character Template

Again, your hero code and Encyclopedia entry should look like this:

---

• name = ___

1.) This is the name that will actually appear in-game. It needs to be written on quotation marks ("like this") and multiple words can be used.

---

• icon = ___ (Optional)

2.1) Defines the icon your character will have. If this is absent, the default icon for the defined "Unit Type" (see 3.1) will be used.

2.2.) It is possible to create custom icons (try editing some of existing ones on Photoshop!). This requires two steps: (a) Add an image to a valid mod folder; (b) Write a Notepad file like this telling the game the image is a valid icon (look other files on the mod to have a better idea).

2.3) All image icons can be seen at <Steam\steamapps\common\Wyrmsun\GRAPHICS>.

2.4.) Not all of images are implemented as icons right now, but you can find the names of implemented ones at <Steam\steamapps\common\Wyrmsun\DATA\ICONS> (New Format) or at <Steam\steamapps\common\Wyrmsun\SCRIPTS> (Old Format).

Some minor spelling ajustments might be needed if you copy something on the Old Format.

---

• unit_type = ___

3.1) Defines what kind of unit your Hero character will be (Ex.: swordsman, archer, knight, worker, etc.).

3.2.) You can create new unit types or find existing ones by looking on "Steam\steamapps\common\Wyrmsun\data\unit_types\units" ("New format"); or on "Steam\steamapps\common\Wyrmsun\scripts\civilizations\" ("Old format").

Some minor spelling ajustments might be needed if you copy something on the Old Format.

---

• variation = ___ (Optional)

4.1.) If your "Unit Type" has some sort of icon or body variation (Ex. Different colors of hair or scales), this will define which one of them will be used by your character.

4.2.) It is possible to create custom variations by editing sprites or icons (see 2.2).

4.3.) If this is absent and the "Unit Type" has multiple possible variations, one of them will randomly be chosen when a game starts (Ex.: Your character can have blonde or brown hair in different matches).

---

• forbidden_upgrades = {___} (Optional)

5.1.) If your selected "Unit Type" can level up and transform to multiple "Unit Types", this camp will prevent some of them from being chosen.

5.2.) For example, most default dwarven axefighter heroes have this line of code so they can not become a Yale Rider (a dwarven horseman unit). They will, instead, only be able to upgrade to the better versions of an Axefighter (like a "Dwarven Thane").

5.3) I believe this might also be used to prevent some other skills and abilities from being learnable as well (Ex.: Magic spells like "Stun").

---

• civilization = ___

6.1.) Defines the civilization your character belongs to. I believe this is related to the type of voice or interface elements used by the unit (Ex.: a Dwarven Axe as the Attack button) and other minor details.

6.2.) It is possible to create custom civilizations. You would only have to write a Notepad file with the correct information and move it to the correct folders on a mod. More complex details can be added with custom icons or voice files.

6.3.) Not all Civilizations are fully implemented right now, but you can find the names of implemented ones at <Steam\steamapps\common\Wyrmsun\DATA\CIVILIZATION> (New Format); or at <Steam\steamapps\common\Wyrmsun\SCRIPTS\CIVILIZATIONS> (Old Format).

Some minor spelling ajustments might be needed if you copy something on the Old Format.

---

• default_faction = ___

7.1.) Defines which faction within the main civilization your character belongs to.

7.2.) On the Encyclopedia entry for this character, this will define the default color used by its icon.

7.3.) It is possible to create custom factions with custom colors, soundtracks or interface elements (see 6.2.).

7.4.) Not all Factions are fully implemented right now, but you can find the names of implemented ones at <Steam\steamapps\common\Wyrmsun\DATA\FACTIONS> (New Format); or at <Steam\steamapps\common\Wyrmsun\SCRIPTS\CIVILIZATIONS> (Old Format). Some minor spelling ajustments might be needed if you copy something on the Old Format.

7.5.) I believe that, on Custom Games, this also servers as a requirement before the character appears for recruitment on Town Centers or Mercenary Camps.

---

• gender = male***

8.1.) Defines the gender of your character. Currently, it is only possible to set this to "Male" or "Female".

8.2.) If a character uses a gender that is different from the one used by its Unit Type, he will not appear in-game. (Ex.: "Helya" is character with a female gender that uses the Dwarven Axefighter as her default unit type. Unfortunately, since Dwarven Axefighters currently do not support a female gender, Helya will not appear in-game).

8.3.) This camp can be used in the future, if female variants or female-only units are added.

---

• deities = {___} (Optional)

9.1.) Defines the gods worshipped by your character, from the pool of deities present in the game. This is shown in the Encyclopedia entry of your character.

9.2.) Some deities are also available as research on Temples and provide bonuses. If your character worships those ones, he might gain part of those bonuses, if applicable (though I am not sure).

---

Check the next part for explanation on the rest of the code lines!

---

• Topic introduction

Finally, we are almost over!

On this last topic, I will explain the following lines of code:

• 10. Trait.
  
• 11. Description, Background and Quote.
  
• 12. Base Level.
  
• 13. Base Abilities.
  
• 14. Default Items.
  
• 15. History.

Don't forget to check the last topic for the other lines of code.

---

• trait = ___ (Optional)

10.1.) Defines the personality trait of your character. Personality traits usually are small positive or negative modifiers to an unit stats. They are shown in-game below the unit's name.

10.2.) It is possible to create custom traits with different or more impactful modifiers; or even unique names that reflect something other than a personality trait, like a hierarchical title (Ex.: Joan D'arc / Maiden of France). (see 5.2.)

10.3.) If this is absent, a trait will randomly be chosen when a game starts (Ex.: Your character can have an "Old" or "Intelligent" trait in different matches).

10.4.) Some traits affect the way some variations are randomly picked, if no variation is set (Ex.: Character with an "Old" trait can only have icons and sprites with white hair, if those are available).

10.5.) While custom magical affixes can automatically be applied on new items, custom traits are not added to the pool of traits avaliable to most units. They must be either hardcoded to a character's file or added to a pool where they can appear for each "Unit Type".

---

• description / background / quote = ___

11.1.) Those three camps are only used to add vanity information about your character in its entry on the encyclopedia.

11.2.) "Description" is commonly used as an in-world narration about something (Ex.: "All respected Gandalf because he alone defeated the mighty Balrog).

11.3.) "Background" is commonly used to convey real-world information about something or the inspirations behind it (Ex.: "Before appearing in the works of Tolkien, Gandalf was a dwarven name on nordic mythology").

11.4.) "Quote" is a less used camp on the baseline game. It refers to a direct speech from someone (or a quotation from a book) ("Ex.: "Aye, yoong lad, dat Gandalfe folk ain't for ye tae messin' 'roun' 'im").

11.5.) All of those camps needs to be written on quotation marks ( "like this" ) and writting a second quotation will prevent the remaining text to be showed on the encyclopedia. If you want a quotation mark to appear in-game, you need to write it preceded by a backslash ( like this: \" ).

11.6.) If you want part of the text within any of those camps to be displayed on the next line, you need to write a backslash followed by an "N" ( like this: \n ).

11.7.) The "\n" tecnique can be useful to write poems in the description, or putting some lines on the edge of the screen. It can also be cleverly used to mimick the style used in-game to add "new descritive camps" with different names to suit your needs (Ex.: background = "This hero is based on historical findings by famous scientists.\n\nSpeculation: According to the \"Most Famous Historian\", it is possible that the hero developed blue teeth from eating lots of blueberries, which is the interpretation used by this mod".).

11.8.) Technically, those camps are optional - but not having them will prevent your character from showing in the encyclopedia.

---

• base_level = ___

12.1.) Defines the starting level of your character. It is possible to set a base level lower than what the unit_type normally becomes available (Ex.: Gryphon Riders normally start on level 3 when produced, by a Gryphon Rider character could start on level 1).

---

• base_abilities = {___} (Optional)

13.1.) Defines which of the abilities avaiable to your character's level and unit_type are already chosen.

13.2.) Personally, I never found much sucess on this camp, since your character only seems to unlock learnable abilities after reaching the maximum unit_type upgrade possible (Ex.: Dwarven Axefighters can only learn a skill after becoming a Dwarven Thane and reaching level 4).

---

• default_items = {first_item = {_} / second_item = {_} } (Optional)

14.1.) Overall, this defines which items will start on your character's inventory when they are first played; and modify some of those items' properties, if possible.

14.2.) If you want to add an item that can not be dropped, then set "bound = true". If this line is missing or is set to "bound = false", the item will be able to be dropped and picked by other characters. Having "bound = true" works well for objects that are character-specific (Ex.: "Heldiaz's Favorite Pair of Socks") or are involved in complex quest triggers (Ex.: "Stone That Will Eventually Save the World").

14.3.) If you want to add and item that already comes equipped, then set "equipped = true". If not, don't add it or set it to "equipped = false"). If you want to create a hero that already is somewhat powerful, you may try adding basic weapons and shields without magical effects (Ex.: "Spatha" or "Iron Shield"), and set them to to be equipped.

14.4.) Items that are written on first lines will be added last to the inventory (meaning they will appear on the right-most slots).

14.5.) You can create an item with a custom name and add it to your character inventory (even if it doesn't any magical effects or isn't unique). Just write the desired name on the line "name = "XXXXX" (Ex.: name = "Captain Cool's Cool Beatstick").

14.6.) On Wyrmsun, the magical effects on items are added by giving them 1 magical Prefix and/or 1 magical Suffix with pre-defined stats. You cannot add any effects outside of this method, but you can either create different prefixes/suffixes with your desired stats; or create an item type with baseline stats that will be added on top of prefixes/suffixes.

14.7.) Applying prefixes or suffixes will change the name of your item accordingly. If you change the line "name = XXXXX", then the modified item's name will be overwritten by whatever you put there.

14.8.) All prefixes and suffixes can be found on their files at <Steam\steamapps\common\Wyrmsun\scripts>.

---

• history = {year = { active = _ / faction = _ / location = _ } } (Optional)

15.1.) The "History" camp functions as a set of triggers that can be stored directly into a character's data. In theory, the character should behave consistently across any map that satisfies the conditions, even if he isn't directly coded on the map files.

15.2.) This means that, if this modpack is active, this character will appear on any map that features the following location on this year. "Years" are an internal time measure tracked in-game (but the mapmaker can also determine what the starting year for the map).

---

• Gran Finale

Welp, what a long strange trip it has been!

Thank you for reading my guide. It was really an enormous to first learn all of this - and then compile it for others to use.

Special thanks for @Andrettin (Wyrmsun's developer) for answering my incessant questions and bug reports.

I wholeheartly hope that this guide might help anyone to get into coding for the first time and let out amazing creations for the community to see!

Xoxo,
João Caju