Items & World Objects
Note: The Mod Kit is in early development. This tutorial should get you going adding new items and world objects.
We currently do not have support for organism or block modding, but it's coming!
I will be going through the detailed steps to recreate my ItemTorch example from the video Here We will, however, be going a bit farther. We will also be able to place the torch on the ground and pick it back up!
First off, make sure you followed the instructions in the installation section.
You should have an empty scene with a camera and a directional light. Everything you put in this scene will be packaged
into a mod package.
A mod package is any collection of different kinds of mods which are assumed to have some connection
with each other (e.g. a bunch of placeable items and their corresponding world objects).
They will be exported and delivered to the client together.
Right click on the blank space in the hierarchy and click Make Eco Mod -> Item
Now, you should have an object called [Item Class Name] in your hierarchy. This will be the scripting name of your items and will be the same as the class name in code of this item.
Go ahead and name your item now. We recommend prefixing the Item name with 'Item' so you don't get confused. For the torch example, we call our item class: ItemTorch.
Note: Make sure there's no spaces or non-standard symbols in the name, as C# class names cannot contain these characters
Expand the children of this object and you have:
Any mod is composed of multiple different parts, represented by the child objects of the main object. This is to keep everything coherent and in the same place. Explained, the hierarchy for an item mod is:
- Class Name in the Code
- Tool - If this item is something you hold in your hand, then put the 3d model as a child of this. It will automatically show up in the player's hand when the item is equipped.
- Icon - This is the icon that will show in the player's inventory. The foreground and background section are images that make the final icon.
The icon defaults to Icon_Axe, so let's change that. Click on the Foreground object under the Icon Object in the hierarchy to see:
Just change the sprite to any 128x128 pixels sprite to change the icon of the item.
If you're importing your own icon sprite, be sure to set the 'Texture Type' to 'Sprite' as such:
You can do the same thing for the background to change the back of the item icon.
The tool is optional, if you don't add a child to the Tool object then nothing will be displayed when the item is held in hand.
However, we are making a torch, so we want a torch in hand!
I have already provided a torch prefab, which can be found in Assets/Items/Models/Torch/Torch.prefab. Drag that as the child of Tool and you should be good to go. Feel free to fiddle with the object properties.
Notice that the Tool child is untouched, any changes you make to that object will not be saved, it's merely a placeholder for its children.
Now, before we go any further, let's test to see if this item works by itself. We will also have a chance to look at the code side of things.
Go to Eco Mod Tools -> Export Mods
Click Set Server /Mods/ Directory and when prompted, select the directory ECO/Server/Mods/
Note: this is NOT the /Eco.Mods/ folder, just /Mods/
If done correctly, you'll get a window that looks like this:
Otherwise, please check to make sure you selected the proper directory.
Now, I'll quickly go over the numbered features of the exporter:
- The directory you selected to be exported to, click to change.
- If you wish to overwrite an existing mod package, choose it from this list.
- If you want to create a new package, enter it's name here. Note: Conflicting names will overwrite each other.
- What target platforms you wish the mod to support (Choose only PC, for now)
- If there are new mods in the package, this option will auto-generate C# classes for the mods. More on this later.
- Once configured, click this to export the package.
- Expand this drop down to see a list of the mods to be exported.
Name your mod something new in field (3), then click export.
Your mod package is now installed into your local Eco server and (almost) ready to be used.
If you kept checked option (5), then a C# class has been generated for you. It will be put in ECO/Server/Mods/Items/[ItemClassName].cs
The generated code is subject to change rapidly, but as of time of writing it should be:
using System;
using System.Runtime.Serialization;
using Eco.Gameplay;
using Eco.Gameplay.Items;
using Eco.Gameplay.Players;
using Eco.Shared.Math;
[DataContract]
public class ItemTorch : Item, IPlacesWorldObject
{
public ItemTorch()
{
FriendlyName = "ItemTorch";
}
public override string GetDescription()
{
return "ItemTorch description";
}
public override bool OnActOnBlockRight(Player player, Vector3i block_pos, Vector3i normal)
{
TryPlaceWorldObject();
return true;
}
#region IPlacesWorldObject
public Type WorldObjectToPlace { get { return typeof(ObjectWindmill); } }
public void OnPlaceSuccess()
{
}
#endregion
}
Much of this will change, but briefly going over the current state of the Item classes:
using System;
using System.Runtime.Serialization;
using Eco.Gameplay;
using Eco.Gameplay.Items;
using Eco.Gameplay.Players;
using Eco.Shared.Math;
Standard includes, including the beginnings of our API, most of which will be consolidated into Eco.API in the future.
[DataContract]
public class ItemTorch : Item, IPlacesWorldObject
The attributes denote that this item can be saved by our serializer, and our currently required. ItemTorch extends Item, which is the base class for all Items. IPlacesWorldObject is more complicated. This denotes that this item will place a World Object on the ground when right-click is pressed. More on that in a bit.
public ItemTorch()
{
FriendlyName = "ItemTorch";
}
The friendly name of a mod is the name that is shown to the player, and thus should be something more like "Torch" or "Basic Torch". Go ahead and change that now.
public override string GetDescription()
{
return "ItemTorch description";
}
This is the description of the item presented to the player when they request more info on it. This can be as long as you like, but try to keep it below a paragraph. Describing the functionality of the item is good here.
public override bool OnActOnBlockRight(Player player, Vector3i block_pos, Vector3i normal)
{
TryPlaceWorldObject();
return true;
}
In order to make things easier for our modders, common tasks are handled by the ECO API. One of these tasks is placing World Objects into the environment. It's a common case that an item may be placed down, so all you have to do is call TryPlaceWorldObject() and the world object specified below will be 'ghosted' onto the terrain.
#region IPlacesWorldObject
public Type WorldObjectToPlace { get { return typeof(ObjectWindmill); } }
public void OnPlaceSuccess()
{
}
#endregion
The regions are just for organization. This code block is where you specify the World Object that this Item will place. By default, the Item places ObjectWindmill as a placeholder. There is also a callback OnPlaceSuccess when the item is placed successfully, in case you wish to do other logic during the operation.
If you do not wish for an item to place a WorldObject, simply remove the TryPlaceWorldObject and this region. Also change: public class ItemTorch : Item, IPlacesWorldObject To just: public class ItemTorch : Item And you're good.
That's it for now on the code side of things, we'll revisit this once we have our world object in place.
Open ECO/Server/Mods/Player/PlayerDefaults.cs.
This file contains all the defaults that a player will have.
Under:
public static ItemList GetDefaultInventory()
Add a:
list.AddItem<ItemTorch>(1);
After the others.
The one means that only one of the item will be added to the player inventory on first login.
Assuming everything went right, you should be able to drag the torch item to your inventory and equip it.
In this next section, we'll place the torch on the ground as a World Object and revisit the IPlacesWorldObject section of the code.
For now, let's head back to our EcoModKit project.
A little more about this project first: The EcoModKit project is specifically setup with a development environment that mimics the actual game environment. We are working to make it as seamless as possible. You may save any scene you want here and come back to work on it, but just remember that scenes function as packages - don't get your mods mixed up!
Let's get back to it, make a World Object in the same scene you had earlier with the ItemTorch.
You will have an object with one child:
- World Object Class Name - Same as before, this will correspond to the code file on the server.
- [Replace Me] Object - This is the actual object that will appear in the environment, replace this object with what you want it to look like.
For now, let's call the World Object ObjectTorch.
Replace the child object with the same Torch prefab located in Assets/Items/Models/Torch/Torch.prefab Make sure the base of the torch is touching the XZ plane as if it was the ground.
You can disable other objects in the scene to get a better view, but remember to re-enable them before export!
Your hierarchy for this object should look like:
We use a custom shader for the curved world. This shader and its variants are included in your mod package. Be sure to use them on all the materials for your world objects, else they will appear distorted when viewed at a distance.
This section will come in a bit once a few issues with Occupied Blocks are fixed.
If you'd like to fool around with the (working) system right now, check out the component of the ObjectTorch object.
This will be the same process as before, except this time you will want to Overwrite an Existing Mod, instead of typing the name of the package.
A ObjectTorch class will be generated for you if you have the appropriate option checked. It will be placed in ECO/Server/Mods/World Objects/ObjectTorch.cs and look like:
using System;
using System.Collections.Generic;
using System.Runtime.Serialization;
using Eco.Gameplay.Interactable;
using Eco.Gameplay.Interactions;
using Eco.Gameplay.Items;
using Eco.Shared.Math;
using Eco.Shared.Serialization;
[Serializable, DataContract]
public class ObjectTorch : WorldObject, IPickupable
{
public List<Item> itemsGivenOnPickup { get; set; }
public ObjectTorch(Vector3 position, Quaternion rotation)
: base(position, rotation)
{
itemsGivenOnPickup = new List<Item>() { };
}
private ObjectTorch() { }
public override void OnRPCMessage(BSONObject bsonObj)
{
}
public override void Start()
{
CanPickup = true;
}
}
Most of this is similar to the Item class, but with a few exceptions that I will briefly cover:
public class ObjectTorch : WorldObject, IPickupable
All world objects extend from WorldObject.
IPickupable designates that this object can be picked up using the 'E' key in-game. There are a few components to this.
public ObjectTorch(Vector3 position, Quaternion rotation)
: base(position, rotation)
{
itemsGivenOnPickup = new List<Item>() { };
}
In the constructor for ObjectTorch we specify a list of items to give upon pickup. Change that line to:
itemsGivenOnPickup = new List<Item>() { new ItemTorch() };
This will give the player a torch item when the torch object is picked up.
Everything else in this class can be ignored for now.
Head back to ECO/Server/Mods/Items/ItemTorch.cs.
In it, change the line:
public Type WorldObjectToPlace { get { return typeof(ObjectWindmill); } }
To:
public Type WorldObjectToPlace { get { return typeof(ObjectTorch); } }
Now, the player will place your torch world object instead of a windmill.
That's it! If you run the game the torch should be placeable on the ground, then pickupable again.
Thanks for sticking through what is likely to be the first of many modding tutorials.