Data Storage Types - SWG-Source/swg-main GitHub Wiki

Persistent data about an object that can vary is stored via an Object Variable (“ObjVar”) (also referred to as a Dynamic Variable in the engine). An ObjVar is the ideal storage mechanism if you need the data to persist after the object has been unloaded (offline), that is, the data will be persisted to the database. The primary considerations for using an ObjVar are: (1) Do you need the data to persist? (2) How big is the data? and (3) What is the data structure?

With regards to the second and third questions, note that the value field of an ObjVar is stored in the database as a VARCHAR(1000), meaning it can support a maximum of 2,000 characters. Certain storage needs exceed this, such as a large list of players. SOE handled this using a “Mangled ObjVar” (see library.objvar_mangle) which is a wrapper used to sort, create, and access ObjVars that may extend to be larger than 2,000 characters.

High performance optimization for the engine calls for reducing the number of times Java Native Interface (JNI) methods are called in repeat, and critical path functions (see: Mixing C and Java for High Performance Computing). For example, the “getIntObjVar()” method is used to get an integer type ObjVar from the engine using a “native” method, but having to make an engine call inherently consumed more computation and bandwidth than data that is within the Java Virtual Machine running the scripts. Accordingly, in critical processes, (e.g., the combat loop or other methods that run very frequently) it is preferred to cache data in the JVM using Script or Local Variables.

ScriptVars and LocalVars are alternatives to ObjVars that do not persist data after they are unloaded and are accessed via the methods in library.utils. They also provide support for encoding and decoding of data types, such as dictionaries, that the ObjVar methods do not natively support. Using these methods keeps data in the JVM, but does not allow it to be persisted. The key difference between a ScriptVar and a LocalVar is that a ScriptVar’s authority transfers from GameServer to GameServer. That is, if the object with a ScriptVar moves to another planet, for example (or another region if using multi-server), and you will need to access that data again, use a ScriptVar, whereas if they object won’t move, use a LocalVar. For example, a corpse could use LocalVars because they don’t move once they’re created.