Elixr Mods - EM Framework

Join the Eco Modding Community on discord! : https://discord.gg/5BdXErQ

The Elixr Mods Framework is designed to make modding easier for eco, mods more compatible, and extend what you can do in your server,

As of Version 2.1.0 There are some big changes and the info found here may not be totally correct.
For all documentation on the Elixr Mods Framework please visit this link: https://elixrmods.com/docs/elixr-mods/intro

The documentations section includes a left side nav bar for all sections we have documentation for ( im still not done with everything outside of em-framework will do them as i release more things) and Right side navigation usually used for Page Navigation, the only exception is the introduction page which has quick links to each part of the framework under EM Framework Namespaces, the rest are page navigation links

The em-framework documentation is for Version 2.1.0 Onwards.

Permissions System

While our Permissions system is still under development this is some basic documentation on what we have so far and will be updated as we add more features to it:

Using the EM Permissions system is easy,

What the EM permissions system brings to you is the ability to be able to create new user groups and give them access to commands so long as they are in that group,

Example,

Joe donated to your server, You can create the group called "VIP" and add joe to that group,

You can then assign commands to that group for joe to use:

Say you have teleport commands on the server, you can add the teleport command to the group VIP then Joe can use the teleport command,

Usage for server admins:

By default there are 2 user groups, Admin and Default, These 2 groups can not be deleted

If the user is already an admin they don't need to be added to the admin group, but if the user isn't an admin you can ad them to the admin group and assign your admins certain commands, IE: kick, mod based commands or what ever you feel like

Here is a list of all the commands that a admin/ owner in the server can use:

Commands for giving groups permissions to commands

Code

"/CommandPermissions grant command, groupname " // Used to give groups permission to use a command: Eg:
"/CommandPermissions grant fly, VIP" //this gives the group VIP access to use the /fly command
You cannot assign shortcuts to a command, ie: ElixrMods Auto door has a shotcut command: /ad-on
doing: "/CommandPermissions grant ad-on, VIP" will not work

"/CommandPermissions revoke command, groupname" // Used to revoke a groups permission to a command: Eg:
"/CommandPermissions revoke fly, VIP" // Will take away the ability for the VIP group to use the /fly command
You cannot use shortcodes when revoking a command ie: doing: "/CommandPermissions revoke ad-on, VIP" will not work

"/CommandPermissions setbehaviour admin/user, true/false" //this is used to allow Admins or users default access to their default commands:
ie:
"/CommandPermissions setbehaviour admin, false" // will mean any user that was made an admin will not have access to admin commands anymore and you will need to assign then use of admin commands via a group ie: Group Admin.
"/CommandPermissions setbehaviour user, false" // will mean any user that is not in a group or an admin will not be able to use any command without being in a group

Display More

Shortcuts:

Code

"/grant-command command, groupname"
"/revoke-command command, groupname"
"/behaviour-command admin/user, true/false"

The "command" In the commands is any command in the eco game, regardless if its registered by a mod or a core command!

Creating Groups and adding users to groups commands

Code

"/groups addgroup groupname" // Used to create a new group
"/groups deletegroup groupname" // used to delete a created group
"/groups listgroups" // will list all groups you have on the server
"/groups grouppermissions groupname" // Will list all the permissions the named group has "/groups addusertogroup username, groupname" // will add a user to a selected group or will creat the group then add the user too it
"/groups removeuserfromgroup username, groupname" // will remove a user from that group, if the group doesn't exist it will tell you
"/groups forcesave" //forces the groups system to save everything just incase a save fails

All commands that use a username are case sensitive so make sure your naming is correct otherwise it will say that user doesn't exist

Shortcuts:

Code

"/grp-add groupname"
"/grp-del groupname"
"/grp-list"
"/grp-perms groupname"
"/grp-adduser username, groupname"
"/grp-remuser username, groupname"
"/grp-fs"

Config File Structure - If you are not comfortable editing this file then please just use the in game commands - Located in Configs/Mods

ElixrMods-GroupsDate.json

Code

{
  "Groups": [
    {
      "GroupName": "groupname", // The Name of each group
      "GroupUsers":  [
        {
          "Name": "Username", // The username of the person added to the group
          "SlgID": "slgid", // their slgid if present
          "SteamID": "steamid" // their steamid if present
        }
      ], // Each user in this group
      "Permissions": [ //each command this group has access too
        {
          "$type": "Eco.EM.Permissions.ChatCommandAdapter, em-framework", //do not edit this
          "Identifier": "Command" //Command name
        },
        {
          "$type": "Eco.EM.TP.TeleportConfig, em-tp-9", //This is a custom configuration for another mod using the groups system Do not edit this
          "MaxTeleports": 30, // config setting
          "CalorieCost": 250, //config setting
          "CooldownSeconds": 15, // config setting
          "Expiry": 15 //config setting
        }
      ]
    }
  ],
  "AllUsers": [ // Each user that logs into the server
    {
      "Name": "UserName", // Their username
      "SlgID": "slgid", //Their SLG Id - Can be blank if slg id not present
      "SteamID": "steam64id" //Their Steam ID - Can be blank if steamid not present
    }
  ]
}

Display More

For Modders:

There isn't much you need to do to be able to use our permissions system,

To enforce the use of the permissions system you can do the following:

When creating a Chat Command set the following:

Code

[ChatCommand("Description", "Shortcut", ChatAuthorizationLevel.Admin)]
[ChatSubCommand("Command Parent", "Description", "shortcut", ChatAuthorizationLevel.Admin)]

By setting the commands to be used by admins means server owners can assign these commands to any group and allow users in that group to use these commands regardless of them being admin level commands, this also means a user needs to be in a group to use these commands

If you set them like this:

Code

[ChatCommand("Description", "Shortcut", ChatAuthorizationLevel.User or Leave Blank)]
[ChatSubCommand("Command Parent", "Description", "shortcut", ChatAuthorizationLevel.User or Leave Blank)]

Any user will then be able to use the command unless the server owner turns off users being able to use user commands, However this may cause issues with users using /? command for help with a list of basic commands they would normally be able to use,

Extensibilty:

Modders can also extend on the permissions system with their own commands for other features, This requires you to reference our em-framework.dll and you can do some of the following with it:

Code

namespace Eco.EM.Groups

[ChatSubCommand("CommandPermissions" //This sets your command to be a sub command of our permissions system and allows you to use: /permissions yourcommand,
"Your Command Description", "Your Command shortcut IE: Instead of using /CommandPermissions yourcommand you can use /yourcommand", ChatAuthorizationLevel.Admin // this enforces it to be usable by the permissions system and prevents un-authorized users from using the command, admins by default get access to this)]

Extra info

This is the using hook.

using Eco.EM.Groups;

Code

GroupsManager.API.GetGroup(string group, bool true/false); //This will get a group, if it doesn't exist specify if it will create the group or not
GroupsManager.API.AllGroups() //This will get all of the available groups
GroupsManager.API.UserPermitted(User user, permssion) //This will get all the groups the user is in and check if any of those groups have permission to use the commands

Ease Of Use:
public static void yourfunction(string groupName)
{
Group group = GroupsManager.API.GetGroup(groupName); // assign group to a var to make your life easier when looking for groups
} 
GroupsManager.API.SaveData(); // Used to save your group based configuration to the groups file useful if you want a group to be able to have specific settings

Usings (covers the file manager and chat base):

Code

using Eco.EM;

File Manager:

Code

FileManager.ReadFromFile(Base.SaveLocation, filename); filename you can set

FileManager.WriteToFile(datainput, Base.SaveLocation, filename);

Code

Base.SaveLocation = ServerFolder/Configs/Mods

You can also do this with the file manager for your own folder

Code

FileManager.WriteToFile(datainput, Base.SaveLocation + "/Foldername", filename);
FileManager.ReadFromFile(Base.SaveLocation + "/Foldername", filename);

The file manager will automatically create the directory if it doesn't exist

You can set the file name as a string const and use that or use a direct string:

Code

const string filename = "MyMod";
FileManager.WriteToFile(datainput, Base.SaveLocation + "/Foldername", filename);
or
FileManager.WriteToFile(datainput, Base.SaveLocation + "/Foldername", "MyMod");

Should you not want to use the Base.SaveLocation you can use your own:

Code

FileManager.WriteToFile(datainput, "/Mods/YourFolderHere", filename);
FileManager.ReadFromFile("/Mods/YourFolderHere", filename);

I recommend using the base save location as in case the mods folder gets deleted all your config files will remain safe, All configs are saved in .json format

For Configs:

Code

public PluginConfig ConfigName; //your data structure
public IPluginConfig PluginConfig => ConfigName;

public void LoadConfig()   {    ConfigName = new PluginConfig(configFileName // const string or direct string);    } public void SaveConfig()   {    ConfigName.SaveAsync();   }

Tweaks may be required on your end but you can structure it how you like

Chat Manager

here is for sending server messages:

Code

public Message( string content ) // for sending server based messages is also temporary
public Message( string content, MessageType messageType ) // for sending server based messages that are not temporary
public Message( string content, User user ) // for sending to user is also temporary
public Message( string content, Player player ) //for sending to player is also temporary
public Message( string content, User user, MessageType messageType ) // for sending to user not temporary
public Message( string content, Player player, MessageType messageType ) //for sending to player is not temporary
public Message( string content, MessageCategory chatCategory, DefaultChatTags defaultChatTags ) // for sending server messages and selecting chat tags and chat category is temp
public Message( string title, string content ) // server notifications with title, message type is either popup or annoucement

Example:

Code

bool Send( Message Message ) //To server or player
internal bool SendToPlayer( Message Message ) // to player and switches message type: infopanel - annoucement, okboxloc - popup, msglocstr - temp, servermessagetoplayer - perm
internal bool SendToServer( Message Message ) // to server as annoucement, popup, temp, perm
ChatBase.Send(new ChatBase.Message(string.Format(Localizer.DoStr(appName + "{0} has been teleported to you."), Requester.Name), Receiver)); // this uses vars in text and sends to a user
ChatBase.Send(new ChatBase.Message(string.Format(Localizer.DoStr(appName + "{0} has been teleported to you."), Requester.Name), reciever, ChatBase.MessageType.Type)); This will allow you to say if its a popup or a perm message etc
ChatBase.Send(new ChatBase.Message(string.Format(Localizer.DoStr(""), ChatBase.MessageType.Type))); //this will send to the server
ChatBase.Send(new ChatBase.Message(string.Format(Localizer.DoStr(""), ChatBase.MessageType.Type), user)); //this will send to the user

It can also be simplified:

Code

ChatBase.Send(new ChatBase.Message(Localizer.DoStr("Message"), user)); //This sends to a user
ChatBase.Send(new ChatBase.Message(Localizer.DoStr("Message"), user, messagetype)); //This sends to a user with a specified messagetype like a popup 

There is more to the Custom Chat manager but these will all be included on the website, these are temporary docs for now

Chatmanager Simplified: Easy How To Use:

Code

ChatBase.Send(new ChatBase.Message(string content, user, ChatBase.MessageType.Temporary)); //Will send a temporary message to the user
ChatBase.Send(new ChatBase.Message(string content, user, ChatBase.MessageType.Permanent)); // Will send a permanent message to the user
ChatBase.Send(new ChatBase.Message(string content, user)); //Will default to a temporary message to the user
ChatBase.Send(new ChatBase.Message(string title, string content, user)); //Will send an Info Panel to a user
ChatBase.Send(new ChatBase.Message(null | "", string content, user)); //Will send a Popup Ok box to the user
ChatBase.Send(new ChatBase.Message(string content)); // Will send a Temporary message to all online users on the server
ChatBase.Send(new ChatBase.Message(string content, ChatBase.MessageType.Permanent)); //Will send a Permanent message to all online users on the server
ChatBase.Send(new ChatBase.Message(string title, string content)); //Will send an info box to all online users on the server
ChatBase.Send(new ChatBase.Message(null | "", string content)); //Will send a Popup Ok Box to all online users on the server
ChatBase.Send(new ChatBase.Message(string content, ChatBase.MessageType.GlobalAnnoucement)); //Sends a global annoucement to all players on the server ( or think of it as adding a new notification in the notifications section ) this is great for leaving notifications for offline users

String Sanitizer

our string sanitizer emits all text .tolower() and removes spaces after the "," so you can have text like this read in commands easily: /somecommand thisthing, that thing

It will remove the spaces at the end and start of anything after a comma to allow for more acurate reading of user input

To use: string = Base.Sanitize(string); example:

Code

public static void somecommand(User user, string setting, string something)
{
something = Base.Sanitize(something);
}
/somecommand Food, Pineapple
will read as:
food,pineapple 
or
public static void somecommand(User user, string setting, string something, int amount)
{
something = Base.Sanitize(something);
amount = Base.Sanitize(amount); //this is an int and will not work even if you set .ToString() like so:
amount = Base.Sanitize(amount.ToString()); // this will throw an error, this sanitizer is designed for strings
}
/somecommand Food, Pineapple, 5
will read as:
food,pineapple, 5

Using this can help with conflicts similar to our group system, we have it set so all group names are set to lower so you don't accidently create 4 of the same group by using different cases: ie: Vip, vip, VIp, VIP would all return as vip
Our sanitizer helps protect against whitespaces as well, preventing our groups system from adding in 2 groups of the same name but one containing a white space: ie: "vip" " vip" making sure you get the same group every time