Towbar/Project Zomboid_ API for Inventory Items.md

Project Zomboid_ API for Inventory Items

Auto-converted from PDF using uv run --with pypdf.

Page 1

Project Zomboid API for Inventory Items Document version 1.0

Page 2

Contents Contents .................................................................................................................................. 1 Introduction ............................................................................................................................ 2 1. General description ........................................................................................................... 3 2. Timed Action Architecture ................................................................................................ 4 2.1 Modification of the ‘new’ function ................................................................................. 5 2.2 Realisation of the “getDuration” function ...................................................................... 8 2.3 Split of the “perform” function into “perform” and “complete” ....................................... 9 3. Realisation features of the long Timed Actions ............................................................ 12 4. The use of the sendClientCommand .............................................................................. 14 5. Synchronisation of the creation, deletion and modification of items and objects .... 16 1

Page 3

Introduction This document is for the modders for Project Zomboid and it has the new system of Inventory Items manipulation described, which was developed to prevent cheating. All inventory Items processing in multiplayer are transferred to the server side. That means, that while it’s still possible for the modification on the client side to create an Inventory Item and put it to the inventory, such an item won’t be available for interaction and will be deleted from the inventory after relogin. All items should be created on the server side, and then transferred to the client. Thus an Inventory Item will be in the player’s inventory on both client and server sides. 2

Page 4

1. General description The main way of an Inventory Item creation, deletion and manipulation is to create it in a Timed Action. The Inventory Item creation, deletion and modification should be done on the server side, modifying the player’s inventory on the server side. The player’s inventory on the client side is modified subsequently to be identical to the one on the server side. An alternative way of an Inventory Item creation, deletion and manipulation is to send a command using “ sendCommand “ or “ sendClientCommand “ functions. To do that you have to implement your command processor, that will receive the necessary data, perform cheating checks, create/delete/modify the Inventory Item on the server side, and send the corresponding packets to clients for synchronisation. This way could come in handy while dealing with the Inventory Item manipulation that doesn’t come from the user's actions, e.g. admin powers. 3

Page 5

2. Timed Action Architecture The new implementation of Timed Action allows to execute Timed Action on both the server and the client. To adapt the existing Timed Action to the new architecture the following should be done:

1. Move the Timed Action file from media/lua/client folder to media/lua/shared one. This will allow the script to be loaded by the client as well as the server.
2. Make sure there is a variable of the same name with the same value for each new function argument.
3. Create the getDuration function, which returns the execution time of the Timed Action.
4. Move some code from the ‘perform’ function to the new ‘complete’ function. a) ‘perform’ function: i) performs the actions that are only needed on the client, e.g. animation and sound management; ii) doesn’t contain any manipulations with any items or objects; iii) is performed on the client as well as in singleplayer mode; b) ‘complete’ function: i) contains manipulations with items and objects only; ii) is performed on the server as well as in single-player mode; iii) is executed after ‘perform’ in single-player mode; 5) Add the call of the function sending changes to clients to the ‘complete’ function (see section 4). Let’s take a closer look at the required changes. 4

Page 6

2.1 Modification of the ‘new’ function When running a Timed Action, the game sends it to the server side and restores the Timed Action Lua object. This is necessary for execution of ‘getDuration’ and ‘complete’ functions on the server side. The server receives the list of the ‘new’ function arguments and searches for their values in the variables (fields) of the object. Let’s assume there is a following code: function ISPlaceTrap:new(playerObj, trap, damage, maxTime) local o = ISBaseTimedAction.new(self, playerObj); o.square = character:getCurrentSquare(); o.weapon = trap; o.damage = damage / 20; o.maxTime = maxTime; return o; end Code piece 1 - Example of the incorrect ‘new’ function The game won’t be able to restore such an object on the server side, because the argument names aren’t the same as the names of the variables in the object. The following changes should be made in order for the server to be able to send a Timed Action to the server:

1. Rename playerObj to character . There is a realisation of the ISBaseTimedAction.new function In Code piece 2, and we could see that this function saves the argument into the variable named ‘character’.
2. Rename the “ trap ” argument to “ weapon ”, because the value of the “ trap ” argument is saved into the “ weapon ” variable.
3. It is necessary to get rid of saving the changed “ damage ” value into a variable with the same name. Otherwise, if we run such a timed action with “ damage ” equal to 1000, then an object will be created with the “ damage ” variable equal to

When this object is transferred to the server side, this constructor is called again, and it’ll get the value of 50 as an argument of damage. As a result, the server will get an object with 5

Page 7

damage value equal to 2. To prevent this from happening, the incoming values should be kept unchanged. 4) The execution time of the Timed Action also shouldn’t be transferred as an argument, as it created a vulnerability where a cheater can perform Timed Actions instantly changing the time argument. To avoid this, the game uses the “ getDuration ” function to calculate the Timed Action execution time on the server side. function ISBaseTimedAction:new (character) local o = {} setmetatable(o, self) self.__index = self o.character = character; o.stopOnWalk = true; o.stopOnRun = true; o.stopOnAim = true; o.caloriesModifier = 1; o.maxTime = -1; return o end Code piece 2 - realisation of the ISBaseTimedAction:new function After following all the suggestions you’ll get the code given in Code piece 3. function ISPlaceTrap:new(character, weapon) local o = ISBaseTimedAction.new(self, character); o.square = character:getCurrentSquare(); o.weapon = weapon; o.maxTime = o:getDuration(); return o; end Code piece 3 - An example of the correct ‘new’ function implementation Currently the game supports the following data types for the arguments of the ‘new’ function:

1. BaseVehicle 2. BloodBodyPartType 3. BodyPart 4. Boolean 5. CraftRecipe 6. Double 7. EvolvedRecipe 6

Page 8

8. FluidContainer 9. Integer 10. InventoryItem 11. IsoAnimal 12. IsoDeadBody 13. IsoGridSquare 14. IsoHutch.NestBox 15. IsoObject 16. IsoPlayer 17. ItemContainer 18. KahluaTableImpl 19. MultiStageBuilding.Stage 20. PZNetKahluaTableImpl 21. Recipe 22. Resource 23. SpriteConfigManager.ObjectInfo 24. String 25. VehiclePart 26. VehicleWindow 27. null Serialisation realisation is in the PZNetKahluaTableImpl class. It should also be noted that while passing an object, the client sends information to the server to search for the corresponding object on the server side. After that the server searches for the corresponding object and uses it as an argument. For this reason, the game cannot transfer as an argument an object created on the client side. 7

Page 9

2.2 Realisation of the “getDuration” function The “ getDuration ” function is used by the server to fetch the time needed to execute the Timed Action. However, the client can also use this function, using the following code in the ‘new’ function. o.maxTime = o:getDuration(); Code piece 4 - the usage of the getDuration function in the ‘new’ function to receive the execution time of a Timed Action The “ getDuration ” function returns the execution time of the Timed Action in cycles. To convert the time in seconds to the value that the “ getDuration ” function should return, divide the time by 0.02. That is, for a Timed Action that should last 1 second, the “ getDuration ” function should return a value of 50. For an action that is executed instantaneously, it is recommended to return the value ‘1’. For infinite Timed Actions the “ getDuration ” function should return the value ‘-1’. Also this function should return the value 1 if the TimedActionInstant cheat is enabled. Here’s an example usage of this function for Timed Action that lasts 1 second. function ISPlaceTrap:getDuration() if self.character:isTimedActionInstant() then return 1; end return 50 end Code piece 5 - Typical realisation of the getDuration function, returning the 1 second time 8

Page 10

2.3 Split of the “perform” function into “perform” and “complete” It is necessary to split the “ perform ” function into 2 functions: “ perform ” and “ complete ”. Both of these functions are executed at the end of Timed Action execution. The client executes only the “ perform ” function, and the server executes only the “ complete ” one. Singleplayer first executes “ perform ” and then “ complete ”. The “ perform ” function must contain code that is not related to modifying items and objects. This can be code to control sounds, animation, interaction with UI, etc. The “ complete ” function must contain code for items and objects modification. This function cannot contain code that cannot be called on the server side. Let’s take a look at such a split, using ISAddFuelAction as an example. function ISAddFuelAction:perform() self.character:stopOrTriggerSound(self.sound) self.item:setJobDelta(0.0); if self.item:IsDrainable() then self.item:Use() else self.character:removeFromHands(self.item) self.character:getInventory():Remove(self.item) end local cf = self.campfire local args = { x = cf.x, y = cf.y, z = cf.z, fuelAmt = self.fuelAmt } CCampfireSystem.instance:sendCommand(self.character, 'addFuel', args) -- needed to remove from queue / start next. ISBaseTimedAction.perform(self); end Code piece 6 - The obsolete realisation of the ‘perform’ function for the ISAddFuelAction timed action. This function contains the code to control the interface and sound, manipulate objects, and the synchronisation code using the command. 9

Page 11

Let’s keep in this function only the code for interface and sound control. function ISAddFuelAction:perform() self.character:stopOrTriggerSound(self.sound) self.item:setJobDelta(0.0); -- needed to remove from queue / start next. ISBaseTimedAction.perform(self); end Code piece 7 - The new realisation of the “perform” function of the ISAddFuelAction timed action We’ll create a new function called “ complete ” and put the code there to manipulate the objects. We also have to perform an action that was previously executed by sending the “ addFuel ” command. If we look at the “ addFuel ” command realisation, we’ll find the following code: function SCampfireSystemCommand(command, player, args) if command == 'addFuel' then local campfire = campfireAt(args.x, args.y, args.z) if campfire then campfire:addFuel(args.fuelAmt) end … Code piece 8 - Implementation of the “addFuel” command handler Apparently, the coordinates of the campfire were sent to the server. Then the server was finding the campfire on the map and performed the “ addFuel ” function. As the “ complete ” function is going to be performed at the server side, we don’t have to send the command anymore. We can directly get an object and perform the required function. So we change the Code piece 9 to the code from the command handler you can see in Code piece 10: CCampfireSystem.instance:sendCommand(self.character, 'addFuel', args) Code piece 9 - Sending of the addFuel command from client to server local campfire = campfireAt(args.x, args.y, args.z) 10

Page 12

if campfire then campfire:addFuel(args.fuelAmt) end Code piece 10 - Search and modifying of the object We also change the call of the local “ campfireAt ” function to its realisation, which is given above. local function campfireAt(x, y, z) return SCampfireSystem.instance:getLuaObjectAt(x, y, z) end Code piece 11 - Realisation of the campfireAt function As a result we get the following function: function ISAddFuelAction:complete() if self.item:IsDrainable() then self.item:UseAndSync() else self.character:removeFromHands(self.item) self.character:getInventory():Remove(self.item) sendRemoveItemFromContainer(self.character:getInventory(),self.item) end local campfire = SCampfireSystem.instance:getLuaObjectAt(self.campfire.x, self.campfire.y, self.campfire.z) if campfire then campfire:addFuel(self.fuelAmt) end return true end Code piece 12 - The new realisation of the ‘complete’ function of the ISAddFuelAction timed action 11

Page 13

3. Realisation features of the long Timed Actions To implement Timed Actions that perform actions during execution, such as pouring liquids or reading books, it is necessary to use an additional Anim Event emulation API. To implement such an action the implementation of the “ serverStart “ function is needed, which is executed on the server side when the Timed Action starts. In this function, call the “ emulateAnimEvent ” function to set up the AnimEvent emulator. After that, you need to write an implementation of the “animEvent” function, which will be called periodically to execute a part of the whole action. To stop such an action, the server-side function self.netAction:forceComplete() should be called. You could use the “ self.netAction:getProgress() ” function to get the progress of the action in the animEvent function on the server side. Let’s take a look at the examples. First here’s the realisation of the serverStart function: function ISChopTreeAction:serverStart() self.axe = self.character:getPrimaryHandItem() emulateAnimEvent(self.netAction, 1500, "ChopTree", nil) end Code piece 13 - Example of realisation of the serverStart function The “ emulateAnimEvent ” function takes the following arguments: 1) “NetTimedAction” - always equals to self.netAction ; 2) “duration” - a period in milliseconds; 3) “event” - a name, that will be sent to “ animEvent ” function; 4) “parameter” - a stock parameter for the “ animEvent ” function. An example of implementation of the “ animEvent ” function is shown in the code piece

function ISChopTreeAction:animEvent(event, parameter) 12

Page 14

if not isClient() then if event == 'ChopTree' then self.tree:WeaponHit(self.character, self.axe) self:useEndurance() if self.tree:getObjectIndex() == -1 then if isServer() then self.netAction:forceComplete() else self:forceComplete() end end end else if event == 'ChopTree' then self.tree:WeaponHitEffects(self.character, self.axe) end end end Code piece 14 - Example of realisation of the “animEvent” function This function on the client only reproduces tree chopping effects using the “ WeaponHitEffects ” function. But in singleplayer, and on the server, this function calculates the damage the tree takes from axe hit using the self.tree:WeaponHit(self.character, self.axe) function. Finally, when the tree is chopped down - it stops the infinite Timed Action: if isServer() then self.netAction:forceComplete() else self:forceComplete() end Code piece 15 - Realisation of the end of the Timed Action 13

Page 15

4. The use of the sendClientCommand The “ sendClientCommand ” function is executed on the client and sends a command whose handler is on the server. If this function is called in a singleplayer game the handler of this command will also be called by the game. The “ sendClientCommand ” function has the following arguments: 1) IsoPlayer “player” - optional argument, player’s object; 2) String “module” - the name of the module for which the command is sent;

3. String “command” - the command name; 4) KahluaTable “args” - table with arguments. sendClientCommand(self.player, "vehicle", "getKey", { vehicle = self.vehicle:getId() }) Code piece 16 - Sending the getKey command for the ‘vehicle’ module with an argument vehicle = self.vehicle:getId() Upon receiving the client command the server calls an OnClientCommand event with the following arguments: module, command, player, args. local VehicleCommands = {} local Commands = {} function Commands.getKey(player, args) local vehicle = getVehicleById(args.vehicle) if vehicle and checkPermissions(player, Capability.UseMechanicsCheat) then local item = vehicle:createVehicleKey() if item then player:getInventory():AddItem(item); sendAddItemToContainer(player:getInventory(), item); end else noise('no such vehicle id='..tostring(args.vehicle)) end end VehicleCommands.OnClientCommand = function(module, command, player, args) if module == 'vehicle' and Commands[command] then 14

Page 16

Commands[command](player, args) end end Events.OnClientCommand.Add(VehicleCommands.OnClientCommand) Code piece 17 - Example of implementation of the getKey command handler on the server side The Events.OnClientCommand.Add() function call sets the OnClientCommand event handler. After executing this function, receiving any command will result in calling the function indicated as an argument. In this case the VehicleCommands.OnClientCommand function is the handler for the OnClientCommand event. The VehicleCommands.OnClientCommand function checks if the module is set equal to “vehicle” and if there is a function with the name corresponding to the command name in the Commands table. Then the function calls the corresponding function by sending it the “player” and “args” arguments. The Commands.getKey function is a handler of the “ getKey ” command. This function works only if the player has the UseMechanicsCheat permission. In case if the player has the appropriate permission and the required vehicle is found on the server side then it creates the key InventoryItem on the server side using the “ createVehicleKey ” function, and after that adds it to the player’s inventory and sends it back to the client side. 15

Page 17

5. Synchronisation of the creation, deletion and modification of items and objects All object changes made in the ‘complete’ function should be sent to clients. The following functions are needed for that:
6. sendAddItemToContainer - adds the InventoryItem to the container; 2. sendRemoveItemFromContainer - deletes the InventoryItem from the container;
7. syncItemFields - synchronises the following variables: condition, remoteControlID, uses, currentAmmoCount, haveBeenRepaired, taintedWater, wetness, dirtyness, bloodLevel, hungChange, weight, alreadyReadPages, customPages, customName, attachedSlot, attachedSlotType, attachedToModel, fluidContainer, moddata;
8. syncItemModData - synchronises the moddata; 5. syncHandWeaponFields - synchronises the following variables: currentAmmoCount, roundChambered, containsClip, spentRoundCount, spentRoundChambered, isJammed, maxRange, minRangeRanged, clipSize, reloadTime, recoilDelay, aimingTime, hitChance, minAngle, minDamage, maxDamage, attachments, moddata;
9. sendItemStats - synchronises the following variables: uses, usedDelta, isFood, frozen, heat, cookingTime, minutesToCook, minutesToBurn, hungChange, calories, carbohydrates, lipids, proteins, thirstChange, fluReduction, painReduction, endChange, reduceFoodSickness, stressChange, fatigueChange, unhappyChange, boredomChange, poisonPower, poisonDetectionLevel, extraItems, alcoholic, baseHunger, customName, tainted, fluidAmount, isFluidContainer, isCooked, isBurnt, freezingTime, name;
10. transmitCompleteItemToClients - add an object to the map; 8. transmitRemoveItemFromSquare - delete an object from the map; 9. sync - synchronise the object change on the map; 10. transmitUpdatedSpriteToClients - synchronise the changed sprite. 16

Page 18

Here are some examples of the code for how to create, delete and manipulate items: local candle = instanceItem("Base.Candle") self.character:getInventory():AddItem(candle); sendAddItemToContainer(self.character:getInventory(), candle); Code piece 18 - Adding InventoryItem to the inventory self.character:removeFromHands(self.weapon) self.character:getInventory():Remove(self.weapon); sendRemoveItemFromContainer(self.character:getInventory(), self.weapon); Code piece 19 - Deleting the InventoryItem from the inventory Here are some examples of the code for how to create, delete and manipulate objects. local trap = IsoTrap.new(self.weapon, self.square:getCell(), self.square); self.square:AddTileObject(trap); trap:transmitCompleteItemToClients(); Code piece 20 - Adding the IsoObject to the map self.trap:getSquare():transmitRemoveItemFromSquare(self.trap); self.trap:removeFromWorld(); self.trap:removeFromSquare(); Code piece 21 - Deleting the IsoObject from the map self.generator:setActivated(self.activate) self.generator:sync() Code piece 22 - IsoObject synchronisation on the map 17