Modding Guide

Capabilities

What can I mod? What can't I mod?

• The Official Map is currently moddable in a very limited way. You can not change the terrain mesh geometry or textures, nor remove any static objects.
• Custom Creatures are currently not moddable in Unity.
• Custom Equipment is currently not moddable in Unity.
• Custom Maps can be made in Unity and run in game.
  • They also no longer fall under NDA, so you are already permitted to host them for players.
• Custom Assets (such as custom objects) can already be added and set up for the client to properly use.
  • This includes adding object or surface collision, transparency colliders or collapsible roofs for houses, as well as object bounds and picker boxes for support players to be able to interact with them.
• Custom Maps currently do not support a proper SFX set up. Both music and environment effects can be placed in the scene for testing and they will play in the client. However, you can not lower or increase the volume in the client properties.
• World Streamer is not supported for modding at this time. This means you can not create a large, open-world environment with custom maps. You can only build content with World Streamer in mind.

Necessary Tools

For the time being, modding is only feasible on Windows machines.

1. Unity 3D editor: Download Unity3D Installer version 2018.1.9 (at least version 5.6). You will need to create an account.
2. Lua editor: Download Sublime Text or any other editor with syntax highlighting, e.g. Notepad++.
3. The latest Legends of Aria Toolkit.

Note: Unity3D useful tip to move the camera: Press right-clight to enter "WASD" camera control mode. Add 'SHIFT' to accelerate camera movement.

Creating a new project, based or not on the Celador map

Cf. this video introducing the setup.

NOTE: You must have first installed a LoA server before to proceed with the direction below.

1. Launch Unity3D, create a "New" "3D" project, assigning it with a name, preferably in a folder of your choice. No Unity Analytics is needed.
2. Import assets: in "Assets" menu, "Import Package" and import both "Effects" and "Environment" (Press "Import" for each new window opening).
3. From the Assets store (in "Window" menu, select "Asset Store"), search for the "Post Processing Stack" package ("Unity Essentials" from "Unity Technologies").
4. in "Assets" menu, "Import Package", import "Custom Package" and select the Legends of Aria Toolkit you previously downloaded. Click "Import" on the new widow, this will take several minutes.
5. You should now have a new "LoA Toolkit" menu item in Unity3D.
6. Under that new menu item, select "Settings".
7. "Browse" the "Base Path" to reflect the path: <server>\Build\base
8. "Browse" the "mods Path" to reflect the path: <server>\mods
9. Press "Save".
10. If you are editing a mod that you already created, select the consistent mod name in the "Mod" pull-down list (You might have to "save" first and reopen the Settings).
11. If you are starting a new mod, select "Create Mod" under the "LoA Toolkit" menu.

Your Mods folder under <server> should then reflect the structure displayed on the right.

Modding the Celador maps

1. Look in Unity's "Project" widget, select the "Legends of Aria Toolkit" folder and double-click on the "ShardsToolkit.unity" Unity asset (It's a scene map loader helper).
2. Select the "Game" above the viewer window and press the "Play" button on the top right of that same window.
3. You can select any scene map to be loaded by pressing its button.

• For "New Celador", there is an exception: the map is split into sub-scenes because it is very big: Under the "LoA Toolkit" menu, select "Utils" then "World Streamer Manager". You can then select a "Preset" selection of scene respective to the area(s) you are looking to edit. You can alternatively load individual scenes by clicking on them.

1. Switch to the "Scene" view by pressing the "#Scene" button above the Unity viewer (from the "Game" view you currently are on).
2. You can add Prefabs to the map, as well as Seed Objects (cf. below).

Make sure you save your mod after edition.

Modder Tip: Not all files in the base folder are overridable (moddable). Here is a full list of these files:

• ClientIdReference.txt
• ObjectCollisionData.xml
• ObjectTagDefinitions.xml
• mapdata/MAPNAME/StaticCollision.xml

Starting a new map

See this video for more detail.

1. From the "LoA Toolkit" menu, select "Custom Assets", then "Create New Custom Map". You can choose either it's an exterior or interior map. A new "MapData" asset will be create under your new "Untitled" (a least until you save it) unity scene in Unity's "Hierarchy" widget.
2. Create a new terrain, either by right clicking in the "Hierarchy" widget or under the "GameObject" menu, then "3D Object" and "Terrain".
3. You can edit the terrain properties (size, center, texture, etc.) from Unity's "Inspector" widget. You can also use some Unity Terrain generators to help you create terrains easily.
4. You can add Prefabs to the map, as well as Seed Objects (cf. below).

Make sure you save your mod after edition.

Saving your mod

Make sure you have saved your Unity project and saved all your seed objects (see below).

1. When done, select "MapData" in Unity's "Hierarchy" widget. Select "Reset Permanent IDs" (unless you have a script that refers to any Permanent IDs) in Unity's "Inspector" widget and press "Build".
2. Check the "Saving your mod" section below. If you haven't saved the project yet, Unity will require you to save it first.
3. To make sure your server loads your modifications, make sure you consistently edit the "<Mod>" section of the ClusterConfig.xml file, i.e. put your mod name there.
4. If you have created a new map, make sure you add a "<ClientBundle>" subsection in that section and add or edit the consistent "<Region>".
5. Also, make sure you clean up all your server backups before to reload it (careful of what you delete as well, like characters' data, if you're in production).

Dynamic Game Objects (GameObj)

Legends of Aria is a true world simulation in the sense that there are very little arbitrary rules on the dynamic game objects in the world. Dynamic game objects (GameObjs) can be placed anywhere and are defined by their properties. GameObjs that contain a mobile component can move smoothly throughout the world using the pathing algorithm. All GameObjs are created from templates. The template is the definition for the initial state of an object at creation. It defines things like: What does it look like (Client Id)? What is its name? What sorts of behaviors does this object have? etc. Once the GameObj is created, the template is never referenced again and every property about that object can be changed by scripts or god powers.

NOTE: In Lua, the reference type for dynamic game objects is GameObj and we will refer to them as such in this handbook.

Seed Objects

Seed objects are dynamic object that spawns when the server resets or when loaded the first time. Many of these “Seed Objects” are invisible to mortal players and are used as a source for controller scripts. The simplest and most common example of a controller script is a spawner, a behavior that spawns other GameObjs like monsters or animals on the map. In Unity3D, they can be grouped, under "category" or "group", so they can be loaded, saved and edited all at once or separately. Celador base map's Seed Objects are grouped by zone and types.

In Unity3D, to access Seed Objects functionality, in the "LoA Toolkit" menu, select "Dynamic Editors" then "Seed Object Editor".

Loading

If you are editing from the Celador base map, select the "Default" "Mod", otherwise load your module's specific group (if not already loaded). You can select in the "Seed Object Editor" to "Load All Seed Objects" or the specific "Group" that you want to load to edit.

Creating an Instance

It is advised to create groups/categories to have a finer detail of finding, editing and saving/loading of seed objects. In order to do this, click on "Create New Category" on the "Seed Object Editor" window. You can rename each category or seed object from Unity's "Hierarchy" widget. Then you can "Create New Seed Object" from the "Seed Object Editor" window. You will want to drag that "New Seed" object within the consistent category (that you created above) in Unity's "Hierarchy" widget, and rename it. Then select that seed in the "Hierarchy" widget and you will see Unity's "Inspector" widget updating, as well as the bottom of the "Seed Object Editor" window, showing "Seed Object Selected". You can "Select" a template to be used for that seed (You might have to re-select "Default" for "Mod" to get all the templates if you had changed it before).

A useful thing when your editing point-of-view is pointing at the location you want to place your item at, is to use the "GameObject" menu's "Move To View" function. Double-clicking on an object in Unity's "Hierarchy" will move the point-of-view to point to the object's location.

Make sure you save your seed objects when done.

Saving

If you have modified any group of seed object or single object from the "Default" Celador map, make sure you select your "Mod" in the "Seed Object Editor" before saving. Ditto if you want to override any "Default" group, you can also create a group of the same name of a "Default" Celador group to override.

You can choose to "Save All Seed Objects" or select individual groups/categories to be saved. Make sure you save the seeds as often as possible not to loose your work (since it's independent from Unity's scene/project saving).

Properties

If you understand all of the different types of properties and behaviors that can be assigned to GameObjs then you essentially understand how Legends of Aria works at its core. Let’s quickly go through these properties and behaviors (some will be explained in more detail later).

Base Properties

These properties exist on every GameObj in the game. If a property is not defined in the template, it will fall back to its default value (assuming it’s not required)

• ClientId (required) – This is the art asset id the client uses to display this object. It also determines which Shared Object Properties (See section under Lua Script Engine) this object has and their default values.
• Name - Modder Tip: Nearly every string in the game, including names, can be color coded. It uses html color codes in square brackets and is terminated with a dash in square brackets. Example: A blue string would be “[0000FF]Blue String[-]”
• ScaleModifier – Optionally modifies the size of the object by multiplying the default scale of the object by this value.
• Hue – This is a hexadecimal color code in the format 0xARGB. Example: Red is 0xFFFF0000

Mobile Component

This must exist on any object that can move smoothly across the map using the pathing algorithm. Currently, this is limited to players, NPCs and creatures, however, later this could be expanded to vehicles such as carts and boats.

• BaseRunSpeed – Default is currently 6 (units/sec)
• MobileType – This is used to group mobs together for player targeting purposes. For example, if a mobile is “Friendly” then players will need to force an attack on them. This value is also accessible in the Lua script engine.

Object Variable Component

Object Variables are for storage of persistent information about the object. This means it is maintained across server restarts. Object variables are attached to the GameObj itself and are accessible to any behavior, even behaviors attached to other GameObjs. For example, the number of PvP kills could be stored on a player object in the “PlayerKills” object variable.

Modder Tip: Many behaviors expect certain object variables to be set on an object. For example, the ”weapon_base” behavior expects the “WeaponType” object variable to be set.

Script Engine Component

This is the component that creates Lua environments for any behaviors attached to the GameObj. These behaviors define what an object can do. For example, attaching the food behavior to an object makes it able to be eaten, or attaching an AI script to a creature.

Note: Even if your object does not have any Object Variables or Behaviors at creation, it should still have an empty ObjectVariableComponent and ScriptEngineComponent node in its template file. This is because the engine does not yet automatically create these for you when they are needed at runtime. If you are using the template editor tool, this is automatically done for you.

Prefabs

Prefabs are usually static objects that can be place on a map, i.e. a building, trees, etc. You can use "Default" Celador prefabs, which can be found in Unity's "Project" widget, under "Assets", "Legends of Aria Toolkit", "Default Object Library", "Prefabs".

Permanent Objects (PermanentObj)

In order to allow the user to interact with the thousands of rocks and trees on the map without killing server performance, we also have a second, simpler, type of object for them called “Permanent Objects”. These are map objects that never move and have no base properties or behaviors. The only information that is stored for each is a single visual state (Example: a tree could have full, stump and hidden).

Client Only Objects

These are objects that are built into the map and the server has no access to. This means players and other objects cannot interact with them. A simple example of this is grass or a bridge. Collision for client only objects is also built into the map and cannot be changed.

Custom Objects

If the default set of prefabs from LoA isn't sufficient for you, you can create or import your own objects, either from scratch or using assets available from Unity3D's asset store (Under the "Window" menu, "Asset Store").

The following steps are necessary for the game to recognize your objects:

1. In Unity's "Hierarchy" widget, right-click and select "Create Empty" (an alternative is to go in the "GameObject" menu and "Create Empty" from there). It will create a new empty "GameObject" object, that will be referred as "parent" object in the next steps.
2. Rename that "parent" object consistently and, after having selecting it, go in the "Inspector" widget and press "Add Component". Search for "Client Object" and assign it to it.
3. When your camera is pointed at a location you want to visualize the object, and while the "parent" object you created is selected in the "Hierarchy", go in the "GameObject" menu and select "Move To View". It shall be centered on your view, sitting on the ground.
4. You can now import an external object, e.g. from another library or from your own creation, as a children of the "parent" object that you created in the previous steps. It will probably not be added under the object you created right away, thus make sure you drag it there from the "Hierarchy" widget.
5. You might need to apply scaling to that child object so it fits within the scale of the map.
6. If you need Collision detection, so no character can go through that object, you can add 1 or more "Collider"s (i.e. 1 for a tree, several for house walls):
   1. Select the "parent" object and under the "GameObject" menu, select "Create Empty Child".
   2. Rename that new object "Collider" (exactly that name) and move it as the first child of the "parent" object.
   3. Select that "Collider" and in the "Inspector", "Add Component", search for "Box Collider" and select it.
   4. Set the "Box Collider" values in the "Inspector" so it matches what you want.