LibK

GMOD Lua Library for fast and simple development of database backed addons. Support MySQL and SQLite with the same code.

Database

LibK provides a few tools for database interaction:

• Abstraction through models with support for SQLite and MySQL: No mode manual query writing - No more SQL injection
• Possibility to set up a database connection very easily
• Gurantee that every query will be executed, automatic reconnection on database connection interruption

Networking

• Clients can start server transactions that are wrapped as a promise
• Objects (i.e. class instances) can be sent from server to client

Addon Loader

• Easy loading by filename
• Supports file ordering
• No need to manually include files anymore
• Load an addon after gamemode intialization
• Wait until another addon has finished loading

Basics

This example shows a simple addon that will save player joins to the database. In any shared file:

-- Initialize the Addon
LibK.InitializeAddon{
	addonName = "MyAddon",                  --Name of the addon
	author = "Kamshak",                     --Name of the author
	luaroot = "myaddon",                    --Folder that contains the client/shared/server structure
}

MyAddon = {}

LibK.SetupDatabase( "MyAddon", MyAddon )

-- Create a Database Model
MyAddon.PlayerJoins = class( "PlayerJoins" )
MyAddon.PlayerJoins.static.DB = "MyAddon"
MyAddon.PlayerJoins.static.model = {
	tableName = "ps2_plyjoinstreak",
	fields = {
		playerId = "int",
        	joinedTime = "createdTime" --automatically set to time this entry was created
	}
}
MyAddon.PlayerJoins:include( DatabaseModel )

-- Use It
hook.Add( "LibK_PlayerInitialSpawn", "Save Player Join", function( ply )
	local join = Pointshop2.PlayerJoins:new( )
	join.playerId = ply.kPlayerId
	join:save()
end )

Addon Structure

LibK suggests a simple addon structure that seperates code and divides code into shared, server and client folders.

• addons
  • LibK
  • YourAddon
    • lua
      • autorun
        • youraddon_init.lua
      • youraddon
        • client
        • shared
          • sh_0_youraddon.lua
          • sh_config.lua
        • server
          • sv_youraddon.lua

This is purely optional, some features can only be used with this structure however.

Setting up an addon

The file youraddon_init.lua should call LibK.InitializeAddon which automatically adds client and shared files to the lua datapack and the addon reload list. The reload list allows you to fully reload your addon using a console command. It makes sure that all dependent addons are loaded in the correct order.

Shared code is always loaded before server/client specific code. To further specify load orders use numbers in the file names, e.g.:

• sh_0_loadedFirst.lua
• sh_1_loadedSecond.lua
• sh_doesntMatterWhenLoaded.lua

Example file content:

youraddon_init.lua:

--Example:
LibK.InitializeAddon{
	addonName = "YourAddon",                  --Name of the addon
	author = "Kamshak",                       --Name of the author
	luaroot = "youraddon",                    --Folder that contains the client/shared/server structure relative to the                                               --lua folder
}
LibK.addReloadFile( "autorun/youraddon_init.lua" ) --Path to the file so it can be reloaded using the libk_reload command

sh_0_youraddon.lua:

YourAddon = {}

The global addon table is created shared.

sh_config.lua:

YourAddon.Config = {}
YourAddon.Config.startHp = 100 --Example setting

All settings should be put in here. Everything should be commented.

sv_youraddon.lua:

LibK.SetupDatabase( "YourAddon", YourAddon )

The database connection is set up(see below for details)

Setting up a database connection

Generally every addon using LibK should have a global addon table that contains all models.

To get a database connection the function LibK.SetupDatabase( pluginName, pluginTable ) should be used. pluginName a string used to identify the addon and a unique identifier. pluginTable is the global addon table that contains all models.

--Example:
LibK.SetupDatabase( "YourAddon", YourAddon )

The database will connect using the LibK settings (MySQL or SQLite) and initialize all models (create tables etc.) When the datbase has connected the function YourAddon.onDatabaseConnected will be called if it exists.

Models

The main feature of LibK are models, these allow backend independent usage of databases. The plugin generally follows the cakephp conventions.

A model needs to be a class that has a static DB string, which is the identifier given to LibK.SetupDatabase. It then needs a static model table which contains info about the fields. The format is a table with field name as the keys and field type as values. An id field is automatically added to each table and does not have to be specified

Available fieldtypes are:

• string: Maximum 255 Characters long string
• int: Integer value, cannot be NULL
• optKey: Optional key to a different table, can be NULL
• table: Special field, if this is set the object's first level table is serialized and saved to the database, else only class.saveFields fields are saved. This should not be used much but can be useful sometimes when the structure of an object can differ
• bool: True or False (0 or 1)
• player: Datatype to save a player reference by SteamID, difference to string is that some more magic functions work with it.
• playerUid: Int big enough to save a player's unique id
• classname: Special field, automatically saves the classname of the class. If you want to save inherited classes this can be useful
• createdTime: Automatically set to the time the entry was created (timestamp)
• updatedTime: Automatically set to the time the entry was last updated (timestamp)
• time: Time field (timestamp)
• text: Long chunk of text(=MEDIUMTEXT)

Time fields are saved as TIMESTAMP and automatically converted to a number in lua when the object is loaded.

Example model:

KMapVote.Rating = class( "KRating" )

KMapVote.Rating.static.DB = "KMapVote" --The identifier of the database as given to LibK.SetupDatabase
KMapVote.Rating.static.model = {
	tableName = "kmapvote_ratings",
	fields = {
		ownerId = "int",
		stars = "int",
		comment = "text", 
		mapname = "string"
  }
}

KMapVote.Rating:include( DatabaseModel ) --Adds the model functionality and automagic functions

The global plugin table is KMapVote in this case.

To load objects you can use the created automagic functions model.findByField( value ). You can also specify a custom WHERE query using model.getDbEntries( whereString ). These functions return a promise that returns the found objects. Examples:

--Find all ratings owned by player with id 5
KMapVote.Rating.findByOwnerId( 5 )
:Then( function( ratings )
    for _, rating in pairs( ratings ) do
      print( "Map Rating for map " .. rating.mapname .. ":" )
      print( "-> " .. rating.stars .. " stars" )
    end
end )

--Get all ratings:
KMapVote.Rating.getDbEntries( "WHERE 1 = 1" )
:Then( function( allRatings )
    PrintTable( allRatings )
end )

To create a new db entry use model:new( ) then model:save( ) to save it

local rating = KMapVote.Rating:new( )
rating.stars = 4
rating.ownerId = player.GetByID( 2 ).kPlayerId
rating.mapname = game.GetMap( )
rating:save( )
:Done( function( )
  print( "Saved the rating!" )
end )
:Fail( function( errid, err )
  print( "Couldn't save the rating :( errror was: ", err )
end )

References

• Promises: Introduction
• Middleclass: Wiki

License

Copyright (c) 2016 Valentin Funk

The MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.```