Commit bb572252 authored by Kanersps's avatar Kanersps
Browse files

feature: add EssentialMode documentation

parent 152e48e3
---
title: "EssentialMode"
---
{{% alert title="Support Development" color="secondary" %}}
Become a patron today at our [Patreon](https://patreon.com/gdevelopment) and get access to personal support
{{% /alert %}}
### Description
EssentialMode is a framework for FiveM for resources to communicate to eachother and have a common ground to access and save user data. EssentialMode was initially released in january of 2017 and is one of the most used FiveM resources and most used framework for FiveM.
### Features
- Advanced permission system, groups and specific levels
- Easily add commands
- Logs for almost everything
- Made for perfection
- Clean readable code
- User class for easy user manipulation and saving
- Many available resources
- Compatibility made easy
### History
Started in mid 2016 as just being called "Freeroam" it was started as a gamemode to clone GTA onlines functionality, however it quickly grew to be more of its own thing as things grew. Including things like business and house ownership also being able to purchase vehicles and more, but still keeping it's own flair and not becoming a roleplay gamemode as it had many things that would never work in RP. Like on the fly vehicle repairs anywhere you are at a cost.
When freeroam became increasingly harder to manage I decided to write a version 2 for it, which was also the first release I ever did for FiveM(named FiveReborn at the time). It had all the features from v1 but was way more optimized and neatly working, there was however one major flaw: "synchronous database saving". I was saving and loading, basically any database operating I did was on the main thread. Which resulted in disconnects, desync and just overall buggyness. So when everything failed I wanted to write a framework for future gamemodes to rely on in which I decided to start writing "EssentialMode" so when I ever did something stupid again I just had to fix the framework and my gamemodes and other resources would continue to function.
This went on for a while until version 4, when CitizenMP.Server was being replaced by FXServer. This happened in june of 2017 and broke literally every resource and gamemode depending on EssentialMode. This was to do with NeoLua being dropped and a new system being introduced, this was something I couldn't avoid and every resource and gamemode needed some updates to it's interaction with EssentialMode. Luckily we're passed this stage.
Since EssentialMode 4 everything has mostly been good, just a few hiccups here and there but nothing major. But since that version no one had to drastically change their resources to work again and I'm actually quite happy about that.
\ No newline at end of file
---
title: "1.0.0"
weight: 990
---
08 Feb 2017
From now on EssentialMode is no longer a gamemode, this means that the player won’t spawn if you don’t have another one loaded. There is an example gamemode that comes with an example of how to properely spawn a player wherever you want. This means no more teleporting wherever you want the player to actually spawn.
### Changelog
Ban length & Proper ban table.
Cleaner code
Included
EssentialMode
Admin plugin
Example gamemode
### Events
**New**
```lua
-- Gets called when a user command is successfully ran.
AddEventHandler('es:userCommandRan', function(source, command_args, user) end)
-- Gets called when any command is ran
AddEventHandler('es:commandRan', function(source, command_args, user) end)
-- Gets called when an admin command is ran
AddEventHandler('es:adminCommandRan', function(source, command_args, user) end)
-- Gets called when a non existant command is ran. (This can be cancelled to not display the message)
AddEventHandler('es:invalidCommandHandler', function(source, command_args, user) end)
-- This gets called when an admin command is ran, but the user does not have permission to run it.
AddEventHandler('es:adminCommandFailed', function(source, command_args, user) end)
-- This gets called when a chat message is send.
AddEventHandler('es:chatMessage', function(source, command_args, user) end)
```
**Compatibility issues**
This update will not be plug & play compatible with older versions, please use the new SQL.
---
title: "1.1.0"
weight: 980
---
22 Feb 2017
This update has one main thing which I thought was quite important, essentialmode has default settings now. These settings can be changed by any plugin but they are actually meant to be changed by a gamemode and not by a plugin. Plugins can utilize the session settings.
### Changelog
Default settings
Session settings
**Default settings**
```lua
settings.defaultSettings = {
['banReason'] = "You are currently banned. Please go to: insertsite.com/bans", -- The default ban reason, can be a function aswell. The function that gets called has two parameters: function(identifier, username)
['pvpEnabled'] = false, -- Do you want server-wide pvp
['permissionDenied'] = false, -- Can be set to a string, this will be displayed if a user tries to run a command it does not have permission to.
['debugInformation'] = false -- Do you want to log debug information
}
```
### Events
**Changed**
-- When this event gets cancelled now it won't display the default permission denied message.
AddEventHandler('es:adminCommandFailed', function(source, command_args, user) end)
**New**
-- You can set the default settings with this. The parameter is a table, the settings you want to change can be put in here.
TriggerEvent("es:setDefaultSettings", {})
-- Here is an example usage
TriggerEvent("es:setDefaultSettings", {
pvpEnabled = true -- Default false
})
-- This is able to set a session setting, this setting is saved until server restart.
TriggerEvent("es:setSessionSetting", key, value)
-- With this you can get the variable that was saved using setSessionSetting, the callback has one parameter which contains the stored value (or nil).
TriggerEvent("es:getSessionSetting", key, callback)
**Compatibility issues**
No changes
\ No newline at end of file
---
title: "2.0.0"
weight: 970
---
18 Mar 2017
### Changelog
Player class
User groups
General cleanup
Additional settings
Player session variables
**New default settings**
```lua
{
startingCash = 0 -- Set the amount of money you want people to start with
enableRankDecorators = false -- Sets a decorator with the players permission_level on their entity.
}
```
**Default user groups**
```lua
-- First parameter is group name, second is inheritance
-- User group, lowest possible.
user = Group("user", "")
-- Admin, is allowed to run administrative functions
admin = Group("admin", "user")
-- Superadmin, can run any command, bypasses command levels
superadmin = Group("superadmin", "admin")
```
**New user class functions**
```lua
-- Returns permission_level of that player
Player:getPermissions()
-- Sets the permission level to the specified argument
Player:setPermissions(level)
-- Kicks the player with the specified reason
Player:kick(reason)
-- Sets the player money to the specified amount
Player:setMoney(amount)
-- Adds to the current total amount of money
Player:addMoney(amount)
-- Removes from the current amount of money
Player:removeMoney(amount)
-- Sets a session var for the player
Player:setSessionVar(key, value)
-- Gets the specified session var, or nil.
Player:getSessionVar(key)
```
### Events
```lua
-- Adds a new group with the groupname of your choise, you can make it inherit from custom groups or from the main ones. Inhereting from superadmin means that group has access to everything.
TriggerEvent("es:addGroup", "groupname", "inherits")
-- Returns all of the groups inside of the: groups argument
TriggerEvent("es:getAllGroups", function(groups) end)
```
**Compatibility issues**
A. Update your currently database, ( go to the table “users” and add a new column called: “group” with type of VARCHAR. Then edit: “money” change its type to: “double”. )
B. Remove your DB and use the new provided SQL.
---
title: "4.0.0"
weight: 960
---
21 Jun 2017
### Changelog
FXServer compatibility
Native money UI option
Automated update checks
Code fixes
Server exports
Convars (no edits needed to any of the core files)
DB code updates
### User class update
Player ‘class’ has been edited to fix an issue with metatables, as I abused them in NeoLua. So the ‘:’ has been replaced with ‘.’ example:
```
user:setMoney(500)
-- needs to be
user.setMoney(500)
```
### Events
No changes
**Compatibility issues**
Not compatible with CitizenMP.Server anymore
---
title: "4.4.0"
weight: 950
---
06 Aug 2017
Finally what people have been wanting, MySQL support. Well kind of, there is support for intercepting data and manipulating it yourself. Anyway, this comes with a resource that will make MySQL work again for the base data that comes with EssentialMode!
MySQL support
### How to use MySQL.
Download esplugin_mysql
Make sure you have MySQL-Async installed and working
Import the SQL file that comes with esplugin_mysql
Set this convar in your server configuration: set es_enableCustomData 1
Make sure that your load order is correct, make sure essentialmode starts before esplugin_mysql and MySQL-Async starts before essentialmode
Start the server
Stop whining at @Kanersps about MySQL kthx
On how to implement your own data saving take a look at esplugin_mysql
### Logging
You can enable logging by setting the default settings enableLogging to true, when you do that a log file will be created every day with what happened, for example when admin commands are ran or when someone is kicked. It will also log some errors that may happen
Wrappers
### Wrappers
Client wrappers for the user are available now, you can use these by either doing:
`client_script '@essentialmode/server/player/wrappers.lua'`
OR
`local user = exports.essentialmode:getUser()`
In any file you want to use it in, the previous statement will make the user table available in your entire resource.
### Events
No changes
**Compatibility issues**
No changes
\ No newline at end of file
---
title: "4.4.5"
weight: 940
---
14 Aug 2017
### Changelog
Fixed some permission inheritance issues. If you want a user like group let’s say “cop”, make it inherit from nothing.
Fixed logging issues with folder structure changes, it will now save into the resource rather than into a fixed directory
es_admin2 had some updates and fixes
Misc code cleanup
### Events
No changes
**Compatibility issues**
No changes
\ No newline at end of file
---
title: "4.6.3"
weight: 930
---
25 Aug 2017
### Changelog
Added convar: es_enableDevTools enabled by default. Set to 0 if you want them disabled
Async write fixes while logging
Added license, add this to your mysql database if you don’t have it yet or use the new sql file that comes with the plugin
SteamID check when logging a user in (kicks if it doesn’t exist)
Load user with license instead of steamid if the license is found but the steamid isn’t
Code cleanup
### EssentialMode admin update(s)
When banning it will ban their: steamid, license and ip
### Events
No changes
**Compatibility issues**
No changes
\ No newline at end of file
---
title: "5.0.0"
weight: 920
---
19 Sep 2017
### Changelog
Note: Fully supports es4.x >
Added
Global banlist, can be disabled using es_admin2_globalbans (es_admin2)
Full support for FXServer built in permissions
Roles (For more info read down)
Updated
Permission fixes related to groups
Session var idType automatically assigned based on what ID was used for user loading
License fixes
### Roles
EssentialMode now has a new type of permissions built in called roles , for this to work on custom data models please make sure to handle roles as a data column
Roles adds 3 new functions, also note that roles are permanent until they are removed.
```lua
user.addRole("role")
user.removeRole("role")
user.hasRole("role")
```
Note these are synchronously added but obviously saved asynchronously.
### Events
No changes
**Compatibility issues**
No changes
\ No newline at end of file
---
title: "5.2.1"
weight: 910
---
07 Jan 2019
### Changelog
es_nativeMoneySystem default to off
Removed debug printing
Fixed & added es_pvpEnabled
### Events
No changes
**Compatibility issues**
No changes
\ No newline at end of file
---
title: "6.0.0"
weight: 900
---
12 Jan 2019
### Changelog
Periodic update checking
Removed UI component from base EssentialMode
SQLite as default database now
Now licensed under AGPLv3
Allow disabling of EssentialModes command handler
Much better ACL support
Disabled developer tools by default
### Important note
Follow the installation instructions at https://docs.kanersps.pw/docs/essentialmode/installation so you don’t miss anything. As for updating follow all of that aswell.
SQLite
SQLite is a single file database which doesn’t require any additional setup, if you would like to use this all you have to do is drag and drop EssentialMode into your resources folder and start it. You don’t have to start any external database service at all.
### Events
No changes
**Compatibility issues**
The default database isn't CouchDB anymore. It will now be SQLite to revert back please use the convar es_defaultDatabase
---
title: "6.0.1"
weight: 890
---
12 Jan 2019
### Changelog
Critical security update
### Events
No changes
**Compatibility issues**
No changes
\ No newline at end of file
---
title: "6.0.2"
weight: 880
---
13 Jan 2019
### Changelog
Logging fixes
### Events
No changes
**Compatibility issues**
No changes
\ No newline at end of file
---
title: "6.1.0"
weight: 880
---
10 Mar 2019
### Changelog
Fixed SQLite implementation
Basically made SQLite work
It used to be very shit, now it isn't
I swear it works now
### Events
No changes
**Compatibility issues**
No changes
\ No newline at end of file
---
title: "6.2.0"
weight: 870
---
09 May 2019
### Changelog
SQLite fix for Linux
Metrics to keep insight on what is used most
Change license for all files
### Events
No changes
**Compatibility issues**
PvP enabling has been removed from core EssentialMode
\ No newline at end of file
---
title: "6.2.1"
weight: 860
---
09 May 2019
### Change log
Forgot domain change, so updater didn't work
---
title: "6.2.2"
weight: 840
---
11 Jun 2019
### Change log
Hourly timers instead of checking every 20 minutes
Some formatting fixes
Add possibility of startup messages
\ No newline at end of file
---
title: "6.3.0"
weight: 830
---
14 Apr 2020
### Changelog
Custom prefix for system messages (new Convar ‘es_prefix’ & ‘es_errorprefix’)
Don’t show Zap messages on Zap servers
Removed more unused code to create a cleaner codebase
Support for different identifiers (new Convar ‘es_identifierUsed’)
By default disable metrics, please enable them if you’d like to support development (Convar ‘es_enable_metrics’)
### Notes
Unreleased version only used as a stepping stone to EssentialMode 7.0.0
Added more and released as a full version
\ No newline at end of file
---
title: "6.4.0"
weight: 820
---
20 Apr 2020
### Changelog
Support for live data intergration
\ No newline at end of file
---
title: "6.4.2"
weight: 810
---
29 May 2020
### Changelog
Fix bug with live data intergration
Fix if version API returns non-200 code
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment