How to Make a Mod

So, chances are, you're visiting this page because you're interested in making a mod of sorts. While the game is still in its infancy, there is now an API available that will allow people like yourself to make near any mod you want, with only some limitations.

Mods in Devorar are created through Lua scripts, contained in folders under the "Documents/My Games/Devorar/Mods" directory. You may name your mod's folder anything, though you will need two scripts to make a mod at present:

* roster.lua
* main.lua

The "roster.lua" script is responsible for adding player actors and stages to the roster selection screen, available from the main menu. The steps are quite short and, at most, require an image for them to be displayed with. Meanwhile, "main.lua" contains all of the logic you will needing for your mod.

**Currently, only player actors can be modded into the game. Furthermore, some assets cannot be included in the game at this time. Stages, items, spells, and props will be available at a later date.**

## Preface

To make a mod, you must first understand in brief how the game functions. We will mainly just be discussing player actors for now, but we'll include a few words about the other moving parts of the game.

All characters in Devorar, both NPCs and players, are deemed "actors". All actors have an emote file, which contains all of what they can say or do in response to input, and a handful of assets (which includes the emote picture, unit frame portrait, sound effects, and so on). NPCs and players have different roles from one another, but have very similar faculties underneath and are largely one in the same, as far as the game is concerned.

The player (you) controls your actor through the command field. All player actors have what are called "Acts", individual chunks of script that execute when a particular verb is input. Acts include a payload of input, which can allow you to decide what to have them do, such as who the target is. Conversely, all NPC actors have "Reacts" instead, which are scripted identically, but they only execute when they are the player's target for any given action. NPC actors also have some script that runs every time their turn passes, no matter who was targeted by the player.

In other words, **Acts are pieces of script each directly associated with a verb, and run when the player inputs that verb. Reacts are the NPC version that run when they are the player's target, also each associated with a verb.**

Whenever the player does anything and starts their turn, the game begins a "Rotation". A Rotation goes through every eligible NPC actor, one at a time, having them take their turns in order after the player actor gets to. Turn order is arbitrary and does not correlate with any particular stat. The only outlier is the player's target, whom *always gets their turn second, immediately after the player*.

## Adding to the Roster

The first step of any new player actor or stage is adding them to the roster. You do this through the "roster.lua" script mentioned earlier. Here is an example of what this looks like:

```
newRosterItem = NewRosterDetails()
newRosterItem.ID = "coolguy69"
newRosterItem.Name = "coolguy69"
newRosterItem.Pronouns = Pronoun.they
newRosterItem.Role = Role.pred
newRosterItem.PreviewSprite = ReadSprite("funni.png")
AddToPlayerRoster(newRosterItem);

```

**NewRosterDetails()** is the function you run to make a new RosterDetails object. This is nothing more than a chunk of information you give the game. When you supply it information, you may then add either a player or a stage with these details using the **AddToPlayerRoster()** or **AddToStageRoster()** functions.

It's as simple as that. What you added will appear in the roster when the game next runs. However, it won't yet be playable.

## Making Content

Once you have your new actor or stage in the roster, now you must make content. This is where the "main.lua" script comes in. We will just discuss player actors here for now.

An actor or stage, before it can be played, must be added to the game's loader. The ID for them **must match the ID you supplied with the RosterDetails object earlier**. If they do not match, they will not load properly. Adding to the loader isn't necessary for NPC actors, items, spells, and props; however, it is **required** for player actors and stages.

Here is an example of making a basic actor and adding them to the loader:

```
testActor = NewActor("coolguy69")
testActor.Names = {"Coolguy", "Coolguy69"}
testActor.SetStats({
    [Stat.HP] = 80,
    [Stat.MP] = 20,
    [Stat.MaxHP] = 80,
    [Stat.MaxMP] = 20,
    [Stat.AC] = 16,
    [Stat.STR] = 18,
    [Stat.DEX] = 13,
    [Stat.CON] = 10,
    [Stat.WIS] = 14,
    [Stat.INT] = 8,
    [Stat.CHA] = 13
})

testBehavior = NewBehavior("neutral")
testActor.RegisterBehavior(testBehavior)
testActor.SetActiveBehavior("neutral")

assetData = NewAssetData()
assetData.EmotePicture = ReadSprite("funni.png")
assetData.EmoteData = ReadTextFile("emotes.json")

testActor.PrepAssetData(assetData)
AddPlayerToLoader(testActor)

```

As is, this code (along with the "roster.lua" script we made before) will add a very barebones playable actor to the game, accessible through the roster. We will walk through each step.

Making any new actor requires running the **NewActor()** function, supplied an ID through its sole parameter. As said before, this ID should match the entry we made in the roster. Afterwards, we give it a name...well, multiple names. These are essentially aliases for the actor, with the first one being the primary name the game will use above the rest.

When we want to designate the actor's stats, we can do so through the actor's **SetStats()** method. All that needs to be done is supply a table, as demonstrated in the code above. It's recommended to have HP and MP match their maximum values.

Next, we will want to create what is known as a Behavior. These are big chunks of script that contains all the Acts or Reacts for an actor, and then some. They may be interchanged during runtime to functionally be the actor's states. For now we will want to instantiate one with **NewBehavior()**, supplying the Behavior's desired ID. We will then want to run the actor's **RegisterBehavior()** and **SetActiveBehavior()** methods, the first one giving the Behavior object we made, and the second giving the ID. Setting the active Behavior like this will serve to initialize it. We will add Acts and Reacts to our Behavior later.

After that, we need to instantiate a new AssetData object with **NewAssetData()**. This essentially contains all the assets we'll need, such as images, sound effects, and emotes. This can then be given to the actor through that actor's **PrepAssetData()** method.

Last but not least, we give the actor to the game through the **AddPlayerToLoader()** function. And *tada*, we have a fully playable actor.

## Emotes

The most essential need of any actor is to have emotes to use. We will discuss that here.

Making emotes is extremely simple: You make a JSON file, starting with it looking like this:

```
{
 "ACT\_INVALID": [
 "{0} can't do that right now!",
 "{0} isn't able to do that!"
 ],

 "ACT\_neutral\_inspect": [
 "Thinking."
 ]
}

```

You are making one big table that is full of keys, and a string array associated with each key. Keys need to have a certain formatting to them, but these strings can be anything you want them to be. You can just supply one string for each if you want, though including multiple will expand the possibilities for that emote, with the game selecting randomly from the array when the emote is triggered.

Keys are formatted (for player actors) like so:

**"ACT\_behaviorID\_verb"**

The "behaviorID" part is the Behavior that's necessary to be active at the time for this emote to appear at all. The "verb" part is simply the verb that must be input for this emote to trigger. **The verb MUST be the FIRST one in the synonym group as shown in the vocabulary.**

Conversely, NPC actors have theirs formatted like this:

**"REACT\_behaviorID\_verb"**

There are also some other specially formatted keys you can use for an actor. The only required one is "ACT\_INVALID" or "REACT\_INVALID", which is the fallback emote for when the actor does not understand the action. If this happens, the turn gets passed and the Rotation ends prematurely.

There are many ways to customize the appearance of emotes. The following are rich text tags that are available:

* <b> Text </b> - Makes it bold.
* <i> Text </i> - Makes it italic.
* <u> Text </u> - Gives it an underline.
 Text
 - Render a strikethrough line through it.
* <color=#000000> Text </color> - Makes it a color, with those zeroes being any hex code of your choosing.
* <br> - Force a line break.
* <wiggle> Text </wiggle> - Makes it wiggle. (May not work properly.)
* <shake> Text </shake> - Makes it shake.
* <wave> Text </wave> - Makes it rise and fall in a wave.
* <slide> Text </slide> - Makes it slide.
* <bounce> Text </bounce> - Makes it bounce.
* <rot> Text </rot> - Makes it spin.
* <swing> Text </swing> - Makes it swing back and forth.
* <rainb> Text </rainb> - Makes it a lovely animated rainbow.
* <fade> Text </fade> - Makes it fade.
* <dangle> Text </dangle> - Makes it do a dangling motion.
* <pend> Text </pend> - Makes it swing like a pendulum.

By default there are also some numerical parameters you can include in these strings, which will do the following:

* {0} - Returns the owning actor's name.
* {1} - Returns the input target's name if it's an Act, or will return the sender's name if it's a React.
* {2} - Returns the "part of" the target that was specified in the input.
* {3} - Returns the name of some input entity that's associated with the action, such as a spell or an item.
* {4} - Returns an input phrase. This is only applicable to the "speak" and "question" verbs.

*A dedicated page will be made for this later, including the heap of conditional parameters you can include in keys.*

## A Word about Acts/Reacts

Note that I mentioned emotes trigger from verbs directly, exactly as the Act and React script logic we discussed will. However, this is **only the case by default when there is no Act or React in script for that verb**. It will query from the emote file directly to figure out if the actor can perform (or react to) that verb action at all, in this circumstance, then run the emote and begin the Rotation. Essentially the actor is putting out nothing more than flavor text when this happens, and by themselves *will not do anything* in script. They will be dependent on the reaction their target makes (or for NPCs, what the sender had done) for something to happen. For them to *really* do something, of course, there must be an Act or React for that verb.

Note that scripting an Act or React is not always necessary, and for many actions (like petting someone), just letting the game use your emote file will suffice. Your target will react to getting petted like you expect.

Scripting an Act or React is akin to overriding how the game handles actions with the emote file alone. You're telling the game your actor recognizes that action, regardless of how it appears in their emote file, and you're taking over for it. As a consequence, the emote *will not* appear as it does normally. Fortunately, you can fix that, and do so much more.

*More to be described at a later date, including the "how-to" for scripting Acts and Reacts.*