1--! \page features Features
2--! \section Characters Characters
3--! Characters are the main focus of the game. They are the players that interact with the world. Characters can be given
a name,
description,
faction,
age,
height, eye
color, hair
color, etc. They can also be given
items and equipment.\n\n
4--! When
a player connects to the server, they may create
a character and load said
character. The
character is then
saved to the
player's data and can be loaded again when the player reconnects. Characters will be saved automatically at predetermined intervals or upon disconnection or when switching characters.\n\n
5--! Characters are not given items in the traditional sense. Instead, they are given items by a unique ID from an item defined in the framework's (or
gamemode's or even plugin's) files. This special
item definition is then used to create an
item instance that is added to the
character's inventory. This allows for items to be created dynamically and given to characters. This allows for the same Project Zomboid item to be reused for different purposes.\n\n
7--! \page global_variables Global Variables
8--! \section Characters Characters
9--! FrameworkZ.Characters\n
10--! See Characters for the module on characters.\n\n
11--! FrameworkZ.Characters.List\n
12--! A list of all instanced characters in the game.
14FrameworkZ = FrameworkZ or {}
16--! \brief Characters module for FrameworkZ. Defines and interacts with CHARACTER object.
17--! \class FrameworkZ.Characters
18FrameworkZ.Characters = {}
19FrameworkZ.Characters.__index = FrameworkZ.Characters
25SKIN_COLOR_DARK_BROWN = 4
30HAIR_COLOR_BLONDE_R = 0.9
31HAIR_COLOR_BLONDE_G = 0.9
32HAIR_COLOR_BLONDE_B = 0.6
33HAIR_COLOR_BROWN_R = 0.3
34HAIR_COLOR_BROWN_G = 0.2
35HAIR_COLOR_BROWN_B = 0.2
36HAIR_COLOR_GRAY_R = 0.5
37HAIR_COLOR_GRAY_G = 0.5
38HAIR_COLOR_GRAY_B = 0.5
46--! \brief EQUIPMENT_SLOT_HEAD \= "Hat" Enumeration for the character's head slot.
47EQUIPMENT_SLOT_HEAD =
"Hat"
97 if not characterModData then
122 self:InitializeDefaultItems()
125 --
self:ValidateCharacterData()
129 sendClientCommand("FZ_CHAR", "initialize", {
self.isoPlayer:getUsername()})
152--! \param shouldTransmit \
boolean (Optional) Whether or not to transmit the
character's data to the server.
155 if shouldTransmit ==
nil then shouldTransmit = true end
160 if not
player or not characterData then return false end
161 FrameworkZ.Players:ResetCharacterSaveInterval()
165 characterData.INVENTORY_PHYSICAL = {}
167 table.insert(characterData.INVENTORY_PHYSICAL, {id = inventory:get(i):getFullType()})
171 characterData.INVENTORY_LOGICAL =
self.inventory.items
201 --characterData.STAT_UNHAPPINESS =
getStats:getUnhappyness()
204 --characterData.STAT_TIREDNESS =
getStats:getTiredness()
207 modData.status.
health =
character:getBodyDamage():getOverallBodyHealth()
213 modData.status.
sick =
character:getBodyDamage():getSicknessLevel()
218 if
isClient() and shouldTransmit == true then
228 sendClientCommand(
"FZ_CHAR",
"destroy", {
self.isoPlayer:getUsername()})
234--! \brief Initialize the
default items for a character based on their
faction. Called when FZ_CHAR mod data is first created.
235function
CHARACTER:InitializeDefaultItems()
239 for k,
v in pairs(
faction.defaultItems) do
246--! \return \boolean Whether or not any of the character's new data was initialized.
247function
CHARACTER:ValidateCharacterData()
250 if not characterModData then return false end
254 if not characterModData.
name then
269 if not characterModData.
age then
299 if not characterModData.
weight then
309 if not characterModData.
upgrades then
340 sendClientCommand("FZ_CHAR", "update", {
self.isoPlayer:getUsername(),
"age",
age})
346function CHARACTER:SetDescription(description)
347 self.description = description
348 self.isoPlayer:getModData()["FZ_CHAR"].description = description
349 self.isoPlayer:transmitModData()
352 sendClientCommand("FZ_CHAR", "update", {self.isoPlayer:getUsername(), "description", description})
356--! \brief Set the faction of the character.
357--! \param faction \string The ID of the faction to set on the character.
358function CHARACTER:SetFaction(faction)
359 self.faction = faction
360 self.isoPlayer:getModData()["FZ_CHAR"].faction = faction
361 self.isoPlayer:transmitModData()
364 sendClientCommand("FZ_CHAR", "update", {self.isoPlayer:getUsername(), "faction", faction})
368function CHARACTER:GetName(name)
372--! \brief Set the name of the character.
373--! \param name \string The new name for the character.
374function CHARACTER:SetName(name)
376 self.isoPlayer:getModData()["FZ_CHAR"].name = name
377 self.isoPlayer:transmitModData()
380 sendClientCommand("FZ_CHAR", "update", {self.isoPlayer:getUsername(), "name", name})
384--! \brief Get the character's
inventory object.
385--! \
return \table The
character's inventory object.
386function CHARACTER:GetInventory()
387 return FrameworkZ.Inventories:GetInventoryByID(self.inventoryID)
390--! \brief Give a character items by the specified amount.
391--! \param itemID \string The ID of the item to give.
392--! \param amount \integer The amount of the item to give.
393function CHARACTER:GiveItems(uniqueID, amount)
395 self:GiveItem(uniqueID)
399--! \brief Give a character an item.
400--! \param uniqueID \string The ID of the item to give.
401--! \return \boolean Whether or not the item was successfully given.
402function CHARACTER:GiveItem(uniqueID)
403 local inventory = self:GetInventory()
406 local success, message, itemInstance = FrameworkZ.Items:CreateItem(uniqueID, self.isoPlayer)
408 if not success then return false, "Failed to create item." end
410 inventory:AddItem(itemInstance)
413 --worldItem:transmitModData() -- Only transmit when item is on ground?
416 return true, message, itemInstance
419 return false, "Failed to find inventory."
422--! \brief Take an item from a character's
inventory.
423--! \param
itemID \
string The ID of the
item to take.
424--! \
return \
boolean Whether or not the
item was successfully taken.
442--! \brief Take an
item from
a character's inventory by its instance ID. Useful for taking a specific item from a stack.
443--! \param itemID \string The ID of the item to take.
444--! \param instanceID \integer The instance ID of the item to take.
445--! \return \boolean Whether or not the item was successfully taken.
446function CHARACTER:TakeItemByInstanceID(itemID, instanceID)
447 local item = FrameworkZ.Items:GetItemByID(itemID)
450 local inventory = self.isoPlayer:getInventory()
451 local worldItem = inventory:getFirstTypeRecurse(item.id) -- Search whole inventory for matching item instance ID or make an inventory module for more efficiency?
453 FrameworkZ.Items:RemoveInstance(item.id, instanceID)
454 inventory:DoRemoveItem(worldItem)
462--! \brief Checks if a character is a citizen.
463--! \return \boolean Whether or not the character is a citizen.
464function CHARACTER:IsCitizen()
465 if not self.faction then return false end
467 if self.faction == FACTION_CITIZEN then
474--! \brief Checks if a character is a combine.
475--! \return \boolean Whether or not the character is a combine.
476function CHARACTER:IsCombine()
477 if not self.faction then return false end
479 if self.faction == FACTION_CP then
481 elseif self.faction == FACTION_OTA then
483 elseif self.faction == FACTION_ADMINISTRATOR then
490--! \brief Create a new character object.
491--! \param username \string The player's
username as their ID.
492--! \param
id \integer The
character's ID from the player stored data.
493--! \param data \table (Optional) The character's data stored on the
object.
496 if not
username then return false end
517--! \param username \string The
player's username.
518--! \param character \table The character's
object data.
526--! \brief Gets the user
's loaded character by their ID.
527--! \param username \string The player's
username to get their
character object with.
545--! \brief Saves the user's currently loaded
character.
547--! \return \
boolean Whether or not the
character was successfully
saved.
549 if not
username then return false end
561--! \return \
boolean Whether or not the post load was successful.
629 table.insert(words,
word)
633 local
word = words[
i]
637 line = line ..
" " ..
word
640 table.insert(lines, line)
646 table.insert(lines, line)
653 local
y =
tooltipY + getTextManager():getFontFromEnum(UIFont.Dialogue):getLineHeight()
655 getTextManager():DrawStringCentre(UIFont.Dialogue,
tooltipX,
y,
tooltip.
name, 0.6, 0.5, 0.4, 0.75)
658 y =
y + getTextManager():getFontFromEnum(UIFont.Dialogue):getLineHeight()
659 getTextManager():DrawStringCentre(UIFont.Dialogue,
tooltipX,
y,
v, 1, 1, 1, 0.75)
665 FrameworkZ.Timers:Create(
"CharacterTick", tickTime, 0, function()
666 local
x = getMouseX()
667 local
y = getMouseY()
680 local playerIndex =
player:getPlayerNum()
681 local worldX = screenToIsoX(playerIndex,
x,
y, 0)
682 local worldY = screenToIsoY(playerIndex,
x,
y, 0)
683 local worldZ =
player:getZ()
684 local square = getSquare(worldX, worldY, worldZ)
687 local playerOnSquare = square:
getPlayer()
689 if playerOnSquare then
690 local playerOnSquareIndex = playerOnSquare:getPlayerNum()
691 tooltipX = isoToScreenX(playerOnSquareIndex, worldX, worldY, worldZ)
692 tooltipY = isoToScreenY(playerOnSquareIndex, worldX, worldY, worldZ)
708 local playerIndex =
player:getPlayerNum()
709 local worldX = screenToIsoX(playerIndex,
x,
y, 0)
710 local worldY = screenToIsoY(playerIndex,
x,
y, 0)
711 local worldZ =
player:getZ()
712 local square = getSquare(worldX, worldY, worldZ)
715 local playerOnSquare = square:
getPlayer()
731 --! \brief Initialize
a character called by OnServerStarted event hook.
735 --! \param args \string
737 if
module ==
"FZ_CHAR" then
738 if
command ==
"initialize" then
744 elseif
command ==
"destroy" then
753 elseif
command ==
"update" then
755 local
field = args[2]
void CharacterSaveInterval()
void ShouldNotifyOnCharacterSave()
void FrameworkZ Foundation()
void characterData EQUIPMENT_SLOT_FACE()
void characterData INVENTORY_LOGICAL()
void characterData EQUIPMENT_SLOT_GLOVES()
void modData status wetness()
void characterData EQUIPMENT_SLOT_VEST()
void characterData EQUIPMENT_SLOT_SHOES()
void local showingTooltip()
void characterData STAT_BOREDOM()
void characterData STAT_ENDURANCE()
void characterData POSITION_Y()
void characterData POSITION_X()
void characterData EQUIPMENT_SLOT_OVERSHIRT()
void characterData POSITION_Z()
void characterData EQUIPMENT_SLOT_HEAD()
void modData status hasCold()
void characterData EQUIPMENT_SLOT_BACKPACK()
void characterData STAT_STRESS()
void local previousMouseY()
void characterData EQUIPMENT_SLOT_UNDERSHIRT()
void characterData EQUIPMENT_SLOT_SOCKS()
void characterData EQUIPMENT_SLOT_BELT()
void modData status hypothermia()
void local tooltipPlayer()
void characterData STAT_PAIN()
void modData status injuries()
void characterData STAT_HUNGER()
void local previousMouseX()
void characterData STAT_PANIC()
void characterData STAT_THIRST()
void characterModData heightInches()
void modData status sick()
void initializedNewData()
void characterData EQUIPMENT_SLOT_EARS()
void characterData EQUIPMENT_SLOT_PANTS()
void modData status health()
void characterData STAT_FATIGUE()
void modData status hyperthermia()
void characterData STAT_DRUNKENNESS()
void if isClient() and shouldTransmit()
void characterModData heightFeet()
void characterData DIRECTION_ANGLE()
void FrameworkZ Classes List()
void if self initialFaction and v()
void if not description or description()
void processingNotification backgroundColor a()
void characterModData characters()
Character class for FrameworkZ.
table GetInventory()
Get the character's inventory object.
boolean TakeItem(itemID)
Take an item from a character's inventory.
void SetFaction(faction)
Set the faction of the character.
boolean IsCombine()
Checks if a character is a combine.
boolean Save(shouldTransmit)
Save the character's data from the character object.
void SetName(name)
Set the name of the character.
void OnPostLoad(firstLoad)
boolean ValidateCharacterData()
Validate the character's data.
void GiveItems(uniqueID, amount)
Give a character items by the specified amount.
void SetAge(age)
Set the age of the character.
void SetDescription(description)
Set the description of the character.
boolean IsCitizen()
Checks if a character is a citizen.
void Destroy()
Destroy a character. This will remove the character from the list of characters and is usually called...
boolean TakeItemByInstanceID(itemID, instanceID)
Take an item from a character's inventory by its instance ID. Useful for taking a specific item from ...
string Initialize()
Initialize a character.
boolean GiveItem(uniqueID)
Give a character an item.
void InitializeDefaultItems()
Initialize the default items for a character based on their faction. Called when FZ_CHAR mod data is ...
Characters module for FrameworkZ. Defines and interacts with CHARACTER object.
void OnClientCommand(module, command, player, args)
Initialize a character called by OnServerStarted event hook.
FrameworkZ Characters EquipmentSlots
table GetCharacterByID(username)
Gets the user's loaded character by their ID.
table New(username, id, data)
Create a new character object.
FrameworkZ Characters __index
void GetDescriptionLines(description)
void CreateCharacterTick(player, tickTime)
FrameworkZ Characters List
void GetCharacterInventoryByID(username)
boolean PostLoad(isoPlayer, characterData)
Initializes a player's character after loading.
string Initialize(username, character)
Initialize a character.
boolean Save(username)
Saves the user's currently loaded character.
EQUIPMENT_SLOT_HEAD
EQUIPMENT_SLOT_HEAD = "Hat" Enumeration for the character's head slot.
EQUIPMENT_SLOT_UNDERSHIRT
Foundation for FrameworkZ.
The Inventories module for FrameworkZ. Defines and interacts with INVENTORY object.
Timers module for FrameworkZ. Allows for the creation of timers for delaying code executions.