Pointshop2 documentation¶

Installation¶

To install Pointshop2 simply extract the zip you downloaded into the addons folder. This will give you two folders: addons/pointshop2 and addons/libk.

Next install PAC3, the newest version can always be found here. Download and extract the zip, too. This will give you addons/pac3-master.

Final structure when everything is installed:

• garrysmod

  • addons

    • libk
    • pac3
    • pointshop2

Configuration¶

Pointshop2 requires no initial configuration! Once it is installed you are ready to go! Restart your server and press F3 to open the menu. You can find all settings under the “Management” tab.

FastDL¶

Unless players already have the files from other places, they will see errors or texture problems if there is no FastDL system. If you haven’t already set this up, see here. Pointshop2 automatically uses resource.AddFiles to add all required files to the server downloads. To avoid errors, please upload the following files to your fastdl server:

• addons/pointshop2/materials
• addons/libk/resource

Make sure to upload them into your fastdl’s root folder, i.e. addons/pointshop2/materials to fastdl/materials, NOT fastdl/addons/pointshop2/materials.

Advanced Configuration¶

There are a few options in Pointshop2 that can be used to integrate the script more tightly into your system.

Trail Creation¶

The pointshop comes with a few trails readily available and it is very easy to add your own. If you wish to do this, simply place the files inside materials/trails and as long as this is correct, they will be picked up. When making your own, it is recommended to use a size of 128x128 and in VTF format, as .png can lead to crashes. When handling the .VMT, use these specifics to avoid blurring or blocky previews:

"UnlitGeneric"
{
"$basetexture" "trails/dollar"
"$vertexalpha" 1
"$vertexcolor" 1
}

To get your image to an actual Pointshop item, go to the second tab called Management. Now you should be on a tab called ‘Create Items’, with options to select the type. Go to Trail to bring up the basic settings menu, where you can personalize the item you are going to make. Once you are happy with the name and price, click the image preview next to the file path. This will bring up a box displaying all functioning materials inside /trails. Hover over them to play an animated preview, which will give some indication of how they look in-game. Once happy, save the item and if successful, will be found in Uncategorised Items, located inside the Manage Items tab. The last step is to move it into a category, which can achieved via drag and drop.

Accessory/Hat Creation¶

Hats in pointshop2 are PAC3 items. As well as the ordinary single prop-based hats you’ll find in any Pointshop, here you also have the ability use PAC. This allows you to create animated hats, add particles, position hats interactively onto different models and even create full armor or accessories. This can all be done without any lua knowledge and allows you to easily create hats that are absolutely unique to your server.

When creating a hat you have two options:

1. Using the ordinary PAC3 editor and importing the outfits into Pointshop 2
2. Using the PAC3 editor embedded within the Pointshop2 hat editor

Generally it is recommended to use the second way, this allows you to use the full editor and gives you more options. A common approach is to first create the PAC outfits in sandbox and then use the Hat Creator within the Management Tab to create a pointshop item from it. In gamemodes that do not derive from sandbox (for example TTT or Murder) the PAC editor cannot be used. In this case you can still use the Pointshop2 Hat Editor to create and position hats.

Terms, Agreement and General Guidelines¶

Pointshop 2 is designed to be a quality script. To maintain this experience to the user addons and modifications need to conform to a high technical quality standard. You are obliged to follow and adhere to these terms, otherwise you are not permitted to modify, use or look into the source code of pointshop 2.

Developer License¶

If you do not plan to use pointshop 2 on a server but want to create an addon to it, you can request a discounted developer license. The license is available for 10$ and includes a free code review for a single addon. To request a license please contact Kamshak via e-mail. Please include your experience/previous work and a rough description of what you want to add to the shop.

Developer Options¶

To make development and debugging of the script easier there are a few options for developers. If you experience any errors please also turn these settings on as it will help track errors down.

Within addons/libk/lua/libk/shared/2_sh_libk.lua LibK developer settings can be configured.

Structure¶

The module structure is very simple. Each module is a folder within the lua/ps2/modules folder. Every file in this folder is recursively loaded by the module loader. The realm is determined by the file prefix (sh, cl, sv). Client files are automatically AddCSLuaFile’d.

Within this folder the module description file sh_module.lua needs to be placed. Here you set up the module table (MODULE) which contains information such as the author and name of the module, then register it using Poinsthop2.RegisterModule().

Adding custom Item Types¶

Users should be able to create and modify items through the ingame gui.

To understand the way items are created in Pointshop2 it is important to know that each item is handled on it’s own and is unique. This means that even if the user owns ten items of the same type each is saved and handled individually. Technically, each item is an instance of a item class. Thus each “item” that is displayed for purchase at a shop is actually an item class. Instances of this class are the items which can be found in a player’s inventory.

Internally this is achieved using the following components:

• Persistence: The persistence is the data model that is used to save all user defined properties (for example the model for a playermodel item, but also the item name and description). On server start the persistence is read and classes are dynamically generated.
• Item Base: The item base defines the functionality of an item. This is defined in a lua file within lua/kinv/items/pointshop. Item bases can use mixins and extend existing bases. All item bases should extend base_pointshop_item.
• Item Creator: This is the derma control which is used to create or modify an item. It inherits from DPointshopItemCreator.

A blueprint is defined as the persistence, item base and creator for an item type.

Creating a persistence¶

The first step when creating a custom item type is to create it’s persistence. A persistence needs to be a LibK model, which is done by including the DatabaseModel mixin.

Pointshop2.ExamplePersistence = class( "Pointshop2.ExamplePersistence" )
local ExamplePersistence = Pointshop2.ExamplePersistence

ExamplePersistence.static.DB = "Pointshop2" --Use the database configured for Pointshop2


ExamplePersistence.static.model = {
    tableName = "ps2_examplepersistence", --needs to be unique
    fields = {
        --holds the reference to the basic information (description, name, price)
            itemPersistenceId = "int",

        --Define your custom fields here
            property1 = "string"
    },
    belongsTo = {
        -- Makes LibK automatically join the basic information table each times
        -- it is received from the database
            ItemPersistence = {
                    class = "Pointshop2.ItemPersistence",
                    foreignKey = "itemPersistenceId",
                    onDelete = "CASCADE" --Persistence is deleted when the base is deleted. This is required.
            }
    }
}

ExamplePersistence:include( DatabaseModel ) --include the DatabaseModel mixin

function ExamplePersistence.static.createOrUpdateFromSaveTable( saveTable, doUpdate )
    -- Firstly, save or update the basic item information.
    local promise = Pointshop2.ItemPersistence.createOrUpdateFromSaveTable( saveTable, doUpdate )
    :Then( function( itemPersistence )
        // First we fetch or create our persistence instance
            if doUpdate then
                --We need to update an existing item.
                --Find the instance by using the itemPersistenceId and return it.
                    return ExamplePersistence.findByItemPersistenceId( itemPersistence.id )
            else
                    local exampleInstance = ExamplePersistence:new( )
                    exampleInstance.itemPersistenceId = itemPersistence.id
                    return exampleInstance
            end
    end )
    :Then( function( exampleInstance )
        // Then we update all fields
            exampleInstance.property1 = saveTable.property1

            // And save changes to the database
            return exampleInstance:save( )
    end )

    return promise
end

Creating the item base¶

The next step is to create the item base for your item type. To do this, create a new file within lua/kinv/items/pointshop. The name should be sh_base_<itemname>.lua you can also put your file into a subdirectory. Inside of the item base you can now overwrite any of the pointshop base functions and add item hooks as required.

ITEM.static.generateFromPersistence(itemTable, persistenceItem)¶

Decodes all information from the persistenceItem and adds fields and methods to the itemTable field.

itemTable: A table containing the created class. persistenceItem: An instance of this item’s persistence.

The next step is to make sure that the item persistence can be loaded into a valid instance of the item base. This is done by using the static generateFromPersistence method. This method is pretty much the opposite of the persistence’s createOrUpdateFromSaveTable method (with the exception that a valid item class is created instead of a save table). To generate the item class first call the super class’ method by invoking ITEM.super.generateFromPersistence( itemTable, persistenceItem.ItemPersistence ). Next simple copy your item’s properties over to the item class. You should set these to to the itemTable.static table since they belong to a class itself and not an instance (which would be an instantiated item in the player’s inventory).

Next you need to link the base to the persistence. To do this simply define a static getPersistence method which returns the persistence class used.

Example:

ITEM.PrintName = "Pointshop Example Base"
ITEM.baseClass = "base_pointshop_item"

function ITEM.static.getPersistence( )
    return Pointshop2.ExamplePersistence
end

function ITEM:OnEquip( ply )

end

function ITEM:OnHolster( ply )
    --note that ply == self:GetOwner()
end

function ITEM.static.generateFromPersistence( itemTable, persistenceItem )
    ITEM.super.generateFromPersistence( itemTable, persistenceItem.ItemPersistence )
    itemTable.property1 = persistenceItem.property1
end

Within the item base you can also specify your own, custom icon controls for both, the shop and the inventory.

Adding the clientside creator¶

The last step is to create a custom editor control, which is shown when clicking the create item button. This is very easy to do, simply create a new file inside your module, called D<youritem>Creator. It should inherit from DPointshopItemCreator and overwrite the SaveItem(saveTable) and EditItem(persistence, itemClass) methods. The SaveItem method populates the save table passed as argument with the settings set in the item creator. The EditItem method poulates the editor with the settings stored in the persistence. For ease of access the relevant itemClass is also passed as data from the persistence might be accessible easier in there.

Example template:

local PANEL = {}

function PANEL:Init()
    self.textEntry = vgui.Create( "DTextEntry" )
    self:addFormItem( "Property 1", self.textEntry )
end

function PANEL:SaveItem( saveTable )
    self.BaseClass.SaveItem( self, saveTable )
    saveTable.property1 = self.textEntry:GetText( )
end

function PANEL:EditItem( persistence, itemClass )
    self.BaseClass.EditItem( self, persistence.ItemPersistence, itemClass )

    self.textEntry:SetText( persistence.property1 )
end
vgui.Register( "DExampleCreator", PANEL, "DItemCreator" )

Putting it all together: The blueprint¶

The only thing left to do now is to link the item to the menu and register it with the modules. This is done within sh_module.lua. Simply define all of your components in a Blueprint.

Example:

MODULE.Blueprints = {
{
    label = "Example Item",
    base = "base_example", --The name is deduced from the filename
    icon = "pointshop2/playermodel.png", --Icon
    creator = "DExampleCreator"
},

Creating a slot for your item¶

Slots are created using the function Pointshop2.AddEquipmentSlot()

Example:

Pointshop2.AddEquipmentSlot( "Example", function( item )
    --Check if the item is an example item
    return instanceOf( Pointshop2.GetItemClassByName( "base_example" ), item )
end )

Adding custom Settings¶

Pointshop 2 has a builtin, extensible settings system. A module can add custom settings buttons to the builtin settings tab (Management -> Settings) which can then be used to create a GUI. The system first initializes the settings from the Lua table and copies the defaults, then reads settings from the database. To create custom settings you need the following components: the settings table, a settings button and a settings editor.

MODULE.Settings = {}
MODULE.Settings.Server = {}
MODULE.Settings.Shared = {}

MODULE.Settings.Server.Kills = {
    info = {
        label = "Kill Rewards"
    },
    DelayReward = {
        value = true,
        label = "Delay Rewards until round end",
        tooltip = "Use this to prevent players to meta-game using the kill notifications. Kill points are collected and awarded at round end.",
    },
}

MODULE.SettingButtons = {
    {
        label = "Point Rewards",
        icon = "pointshop2/hand129.png",
        control = "DTerrortownConfigurator"
    }
}

local PANEL = {}

function PANEL:Init( )
    self:SetSkin( Pointshop2.Config.DermaSkin )
    self:SetTitle( "TTT Reward Settings" )
    self:SetSize( 300, 600 )

    self:AutoAddSettingsTable( Pointshop2.GetModule( "TTT Integration" ).Settings.Server, self )
    self:AutoAddSettingsTable( Pointshop2.GetModule( "TTT Integration" ).Settings.Shared, self )
end

function PANEL:DoSave( )
    Pointshop2View:getInstance( ):saveSettings( self.mod, "Shared", self.settings )
end

derma.DefineControl( "DTerrortownConfigurator", "", PANEL, "DSettingsEditor" )

Adding custom Tabs¶

It is possible to add new tabs to various sections of the shop. You can add a tab to the top navigation by using Pointshop2:AddTab(). Inside of the inventory tab you can add pages to the side navigation by using Pointshop2:AddInventoryPanel(). It is also possible to add new pages to the side nav of the management tab by using Pointshop2:AddManagementPanel().

Types of Hooks¶

There are two types of hooks that you can use to customize looks and behaviour:

1. Layout Hooks: These are always called after initialization of the component. You can use this hook to replace components with custom components or to reposition components.
2. Paint Hooks: These work like the normal panel:Paint hooks, use this to customize the appearance of the different panels.

If you are missing a hook on a component that you want to customize, please send Kamshak a pm on coderhire.

Fonts¶

Fonts are defined as skin properties and can be customized through a custom skin as well.

Modules¶

class Blueprint¶

A blueprint defines all properties needed for a custom item.

class SettingsCategory¶

A table representing a category that contains one or more settings. The category’s path is indicated by it’s key in the table. The info key is used to provide a readable name for the category to be used in the configurator component. It contains multiple Settings, the path is again provided by the key.

class MODULE¶

The module information table. Contains information such as a module’s blueprints and settings. This is to be defined in the module’s sh_module.lua

Name¶

The name of the module.

Author¶

The author of the module

RestrictGamemodes¶

A table containing gamemodes that this module is restricted to. The module will only be loaded if the active gamemode is in the list.

Blueprints¶

A table containing Blueprint s that players can use.

Settings¶

A table containing the settings of the module. A seperate table for each realm exists. Settings.Server is only sent to admins when changing the settings, Settings.Shared is synced with all clients. Accessing Settings is done by calling Pointshop2.GetSetting() . Each realm settings table defines Settings that can be accessed and configured easily and can contain multiple SettingsCategory s. Settings registered this way are automatically saved the the database when changed.

SettingsButton¶

A table containing information about the settings button that will show up in the management tab. The table has three elements:

label: The label of the button icon: The icon of the button control: The derma control that is created when clicking the button

Poinsthop2.RegisterModule(MODULE)¶

Registers a MODULE to be used with Pointshop 2.

Pointshop2.GetSetting(moduleName, path)¶

Retrieves a setting value that was defined in MODULE.Settings. Automatically uses the default or database saved value.

• modName: The MODULE.Name of the module where the setting is defined
• path: The category and name of the setting, seperated by a ”.”

Example:

print(Pointshop2.GetSetting("TTTIntegration", "RoundWin.Innocent"))

Pointshop2.AddEquipmentSlot(name, itemValidFunction)¶

Registers a new equipment slot.

Name:label of the slot that is shown underneath the slot’s panel in the inventory. itemValidFunction: A function that takes an item as an argument and returns whether or not it can be equipped in the slot.

Pointshop2:AddTab(label, controlName, shouldShow)¶

Adds a new tab to the top navigation of the pointshop.

• label: The label of the tab.
• controlName: The derma control that is created as panel.
• shouldShow: optional A function returning whether or not the player should be able to see this tab.

Pointshop2:AddManagementPanel(label, icon, controlName, shouldShow)¶

Adds a new tab to the side navigation of the management panel.

• label: The label of the tab
• icon: The tab’s icon
• controlName: The derma control that is created as panel
• shouldShow: optional A function returning whether or not the player should be able to see this tab

Example:

derma.DefineControl( "DPointshopManagementTab_Settings", "", PANEL, "DPanel" )

Pointshop2:AddManagementPanel( "Settings", "pointshop2/advanced.png", "DPointshopManagementTab_Settings", function( )
    return PermissionInterface.query( LocalPlayer(), "pointshop2 managemodules" )
end )

Pointshop2:AddInventoryPanel(label, icon, controlName, shouldShow)¶

Adds a new tab to the side navigation of the management panel.

• label: The label of the tab
• icon: The tab’s icon
• controlName: The derma control that is created as panel
• shouldShow: optional A function returning whether or not the player should be able to see this tab

class Configurator¶

Interface for Configurator controls. Used by the settings section.

SetModule(module)¶

Passes the MODULE table to the control.

SetData(data)¶

Passes the Settings as retrieved from the server to the control. data contains Server and Shared settings merged together.

Player integration¶

class Wallet¶

In Pointshop 2 points are stored in a player’s wallet. A wallet is a LibK model instance, you can use :save() on it after changing it.

PLAYER:PS2_AddStandardPoints(points, message, small)¶

Awards points to a player. If a message is specified it will show up in their pointfeed.

points: Amount of points given message: Message displayed to the pointfeed small: Use the small print (for bonus points related to a primary event)

PLAYER:PS2_AddPremiumPoints(points)¶

Adds premium points to a player’s wallet.

points: Amount of points given