Creating a custom Pointshop 2 Item: Part 1 - Simple Lua Item

2017-05-15 10:36:38

In this tutorial you will learn to create a custom low-gravity item. When a player equips this item, they get more jump power for as long as the item is equipped.

For this purpose we create:

An item class that defines the item behaviour
An item slot that can hold the low gravity item

NOTE: This tutorial is the first part of a tutorial series to create a full blown pointshop 2 item creator. Part 1, Part 2, Part 3

Prerequisites

To follow this tutorial you will need a copy of Pointshop 2. If you are a developer, please PM me on gmodstore for a free developer license.

To make development a bit nicer, turn on Debug mode in LibK: see here

Step 1: Creating a module

To create a module first create a new addon in the addons folder. Create the following folders: addons/ps2-lowgravity/lua/ps2/modules/lowgravity

Inside this folder all files will automatically be loaded for you. Files prefixed with sv_ are loaded on the server, files prefixed with sh_ are loaded shared and files prefixed with cl_ are loaded on the client. Client and shared files are automatically AddCSLua’d.

To define the module next create a file called addons/ps2-lowgravity/lua/ps2/modules/lowgravity/sh_module.lua with the following contents:

sh_module.lua

local MODULE = {}

MODULE.Name = "PS2 Low Gravity"
MODULE.Author = "Kamshak"

Pointshop2.RegisterModule( MODULE )

The module definition file is used to load the module.
It can be used to define valid gamemodes for your modules and a bunch of other things that we don’t need yet. At the moment it just makes sure that your addon is loaded.

Restart your server and you will see this in your console:

-> Module PS2 Low Gravity registered!

Step 2: Creating the item class

Next we create the item class. The item class contains the code that makes the item function. Item bases are loaded independently from the module and therefore are located in a different folder. Create the following folders and the lua file: addons/ps2-lowgravity/lua/kinv/items/pointshop/sh_low_gravity.lua

sh_low_gravity.lua

ITEM.baseClass = "base_pointshop_item"
ITEM.PrintName = "Low Gravity"
ITEM.Description = "Equip this to get 2x Jump Power!"
ITEM.static.Price = {
    points = 100
}

function ITEM:PlayerSpawn( ply )
    if ply != self:GetOwner( ) then
        return
    end

    local oldJumpPower = ply:GetJumpPower( )
    timer.Simple( 0.5, function ( ) 
        ply:SetJumpPower( oldJumpPower * 2 )
    end )
end
Pointshop2.AddItemHook( "PlayerSpawn", ITEM )

Most should be quite self explanatory: The base used is base_pointshop_item which defines the basic behaviour of all pointshop items.

When the function Pointshop2.AddItemHook is called it registers a hook on the item. Whenever in gmod PlayerSpawn is called, this function is also called on all equipped items that have registered this hook. The arguments of the original hook are passed along to the item unmodified.

Since gmod calls PlayerSpawn for every player that joins, we need to check if the player that spawned is the player that owns this item. Else we would give everybody jump power. Since the default jump power is also set in this hook we put it into a timer to make sure that the item jump power overwrites the default one.

To understand this behaviour it is important to know how an item class is used by the shop:

How the shop uses the item class

Shop Architecture

When a player buys an item a new instance (this is a bit like a copy) of the item is created. Each instance has all functions and properties of the class that it uses. To get the owner of the current item we can use ITEM:GetOwner(), when called from within the item this becomes self:GetOwner().

See your changes

Change the map and open the shop. In the uncategorized section you can now see your newly created item! You can drag it into a category and buy it.

Item

Step 3: Creating the Slot

As said above: Item Hooks are only called for items that are equipped, that means that the user put them into a slot. So we need a slot that can hold the gravity item.

In Pointshop 2 Items don’t really care what slot they are in so slots determine which items they can hold.

Create a new file addons/ps2-lowgravity/lua/ps2/modules/lowgravity/sh_slot.lua:

sh_slot.lua

Pointshop2.AddEquipmentSlot( "Gravity", function( item )
    --Check if the item is a low_gravity item
    return instanceOf( Pointshop2.GetItemClassByName( "low_gravity" ), item )
end )

The function Pointshop2.AddEquipmentSlot(name, validFunction) adds a new slot to the shop. The name parameter sets the name, the the second parameter is a function that is called to check if an item can be put into the slot.

The function receives the item as parameter. Return true if the item can be put in, or false if the item can not be put into the slot.

Here we simply check if the item is an instance of the item class that we created. The name of an item class is deduced from the file name (the prefix is stripped). Since we named our file sh_low_gravity.lua the name is low_gravity.

That’s it! We can now equip the item and jump around.

Item