Game Items

This describes the Game Items (how they are managed on server -> loading,item generation, saving), but also adding a new item, item editing, deletion and management.

This is sub-layout for documentation pages

This was last updated when game had version: dev - 1.6.3

1 Introduction

In order to understand this complex topic, lets have a look at the item-related classes and see what they do.
The Item classes' relationships are summarized in the following class diagram:

Note: Not all instance variables / methods are shown in the diagram, and if some are, it is NOT guaranteed, that in the current version it really reflects the code.
The point of the diagram is to map relationships between the classes and the compositions relationships

2 General (user-level) overview

The user-level description of item functionality (general oveview / items guide for users) can be found here .

3 Structure overview

In order to work with game items, there are 3 phases that we can be in. Eighter we are loading/saving the items from / to sql database, or we are sending the item via network, or we are working with the items in real gameplay.
For all of these phases there are different sets of classes, and the classes allow conversion between one to another.

3.1 Reason

So why do we need 3 sets of classes for representing item, why can not be just have one, which can also send itself to client and be saved to database?
Unfortunatelly, when loading item from database, foreign key IDs must be loaded aswell, and later assemble the entire item using these IDs (match correct item prototype data with item stat generation intervals data). Additionally, when item is loaded for player, we load inventory ID, inventory position, etc., but in real gameplay, this is no longer needed, as the item instance is already parented to correct inventory class instance.
These inventory IDs, positions within inventory, and FK IDs would be completelly useless for the real gameplay, and they would just be confusing programeer:

,,Well, in CharacterOwnedItem there is inventory ID....well it is important I guess, if it is here...isn't it?"

However, some classes do not need another class representation for the other phases, such as StatsDAO, which can be sent to client, saved to database, and also is used in real gameplay...

3.2 Class diagram

The situation is depicted by following class diagram:

Here you can see, that CharacterOwnedItemDAO can be converted to CharacterOwnedItem. Also, CharacterOwnedItem can be converted to ItemPacket.
Let's now have a look on each of these classes, understanding what they do:

3.3 Load / save phase
Please note, that ALL ItemPrototypeDAO that exist in database are loaded upon start of server, and are held in memory forever, acting as local ,,database". ItemPrototypeDAOs are then NEVER saved nor loaded again!

We start with saving / loading phase. This takes place, whenever item is supposed to be loadedd / saved from / to sql database.

Rule of thumb: Classes for loading / saving reflect the SQL database tables

The situation usually is, that we want to load all items that some player owns. For that, we select all from CharacterOwnedItem table, and Instances table, and then (if item has foreign key defined), we proceed to Stats table, Weapon info table, sockets table etc.

As result, we assemble CharacterOwnedItemDAO, into which we nest all the other DAO classes, and we return the CharacterOwnedItemDAO to caller.

So, once data from all the tables is loaded, we get CharacterOwnedItemDAO. Using that, we get ItemPrototypeDAO (because we know the relevant sql ID), we get it from memory (see warning above). Then, we convert the CharacterOwnedItemDAO to CharacterOwnedItem, and using the info we got in the CharacterOwnedItemDAO, we put the converted structure to player's inventory or equipment, or bank...

Lastly, we discard all the database related DAO instances, and they are never used again.

For saving, the oeration is just inverse:

Note: we also first delete the items from database before saving, and we never save inventory / equipment data, if it did not change sice the load

3.3.1 ItemPrototypeDAO

Contains the basic information about an item, such as text token, sqlID, inventory size, stat generation intervals
Data from a database is loaded into these structures.

3.4 Gameplay phase

The main class we work with in gameplay is CharacterOwnedItem class.

3.4.1 CharacterOwnedItem

This is used as a structure to identify an item that is owned by character. Therefore, it has s stat structure or any info that is dynamic.
To know, where the item is (is in inventory, or in equipment?), we simply figure it out by looking in inventory instance / equopment for that user

3.5 Network phase

Here we mainly operate with ItemPacket class, which allows to send the data for any item

3.5.1 ItemPacket

Contains item prototype ID (to identify ItemProtoDAO instance), then StatsDAO, and ItemSocketsPacket

3.5.2 ItemSocketsPacket

Contains only the most inportant info about Item sockets to be sent.
Contains list of ItemPacket class instances (if item is inside a socket)

3.6 StatsDAO

Contains stats for an Item, or for equipment, or for an ability. It is a versatile structure.
Two of these structures can be added or subtracted to allow easy stats manipulation.
If item is dropped, stats are generated for that item, and they are saved into this structure

3.7 ItemBaseStatGenerationLimitsDAO

Contains limits based upon which are the stats (StatsDAO) for the item generated.

3.8 ItemPickup

Represents item as GameObject, that lies on the ground in a map (physically) and can be interacted with (can be picked up)
Contains CharacterOwnedItem which is (upon picking up) moved to player's inventory

4 Sending to client

There are few cases, when item must be sent to the client:

4.1 Dropped item

If an item is dropped on floor, it must be sent to client.
sent is following:

Note: stats are not sent, nor sockets are, since player only can see item name, as it is dropped. If in future stats shall be displayed upon hovering over item, they simply can be sent aswell...

4.2 Item in inventory / equipment

If an item is added to inventory or equipment, sent is following:

Note: other things, such as position is also sent, but that is not what we focus on in this explanation

5 Algorithms / behavior

The following information is no longer up to date, since the game changed.
Additional info:
In version dev - 1.6.3 and older it is no longer like that... applies to [Algorithms / behavior] section only

5.1 Item object creation when dropped

The process is illustrated by the following sequence diagram:

The initiator of the drop is Monster in current project build. That will, however, change in the future. Therefore the actor is not displayed as a class which initiates it ×

5.2 Stats generation
When an item is dropped, stats for that item are generated using stat generation intervals.

5.3 Stats clamping

Problem can be, that user can have an item with already gereated stats, and it would be saved in database.
However, admin would change the stat generation intervals via this webpage, which, however, does not change the stats of user's items.
For that, whenever user's items are loaded by game server, the stats loaded are clamped to match the relevant current stat generation intervals of that item.

6 Editing via webpage

6.1 Adding a new item to the game

In order to add a new item to the game fully, game server must be restarted after adding the item (because all items are loaded from the database only once upon start of server in game version 1.0.3)


6.2 Removing existing item from an entire game

In order to remove existing item from the game completelly, the game server must be shut down before the removal.
This is because if there is Player playing game, having item A in inventory, if the item A would be deleted completely from the database, it is still in the memory of the server, and therefore, upon player logs out, the item will try to be saved to database.
That can cause undefined behavior because the item prototype is no longer in database.


6.3 Editing existing item
Editing existing item works, but is NOT finished, and will NOT affect any existing instances of that item in user's inventories. Changes will apply to only any future created instances of edited item. (as of website version 1.1.3) ×

In order to edit existing item, the game server also must be shut down before the editing.
Reasons are same as when removing the item.