Serialisation – Arma Reforger

From Bohemia Interactive Community
Jump to navigation Jump to search
(Page creation)
 
m (Some wiki formatting)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{TOC|side}}
{{TOC|side}}
This page talks about {{Link|enfusion://ScriptEditor/scripts/GameCode/Serialization/SCR_SerializationContextJson.c;7|SCR_JsonSaveContext}}/{{Link|enfusion://ScriptEditor/scripts/GameCode/Serialization/SCR_SerializationContextJson.c;37|SCR_JsonLoadContext}} and {{Link|enfusion://ScriptEditor/scripts/GameCode/Serialization/SCR_SerializationContextBin.c;7|SCR_BinSaveContext}}/{{Link|enfusion://ScriptEditor/scripts/GameCode/Serialization/SCR_SerializationContextBin.c;30|SCR_BinLoadContext}}.
This page explains serialisation using {{Link/Enfusion|armaR|SCR_JsonSaveContext}}/{{Link/Enfusion|armaR|SCR_JsonLoadContext}} and {{Link/Enfusion|armaR|SCR_BinSaveContext}}/{{Link/Enfusion|armaR|SCR_BinLoadContext}}.




== JSON ==
== JSON ==
{{Feature|informative|
* Passing an empty string as the name parameter into <enforce inline>BaseSerializationSaveContext.WriteValue()</enforce> or <enforce inline>BaseSerializationLoadContext.ReadValue()</enforce> allows for a complex top-level struct to be written/read.
* See also {{Link|Arma Reforger:JsonApiStruct Usage|JsonApiStruct Usage}}.
}}


=== Serialisation ===
=== Serialisation ===


<syntaxhighlight lang="c#">
<enforce>
SCR_JsonSaveContext context = new SCR_JsonSaveContext();
SCR_JsonSaveContext saveContext = new SCR_JsonSaveContext();


string stringValue = "data";
string stringValue = "data";
int integerValue = 123;
int integerValue = 123;


context.WriteValue("key1", stringValue);
saveContext.WriteValue("key1", stringValue);
context.WriteValue("key2", integerValue);
saveContext.WriteValue("key2", integerValue);


// process saved data (export, send, save...), in this case data are exported as json string
// process saved data (export, send, save...), in this case data are exported as json string
dataString = context.ExportToString();
string dataString = saveContext.ExportToString();
</syntaxhighlight>
</enforce>


=== Deserialisation ===
=== Deserialisation ===


<syntaxhighlight lang="c#">
<enforce>
SCR_JsonLoadContext context = new SCR_JsonLoadContext();
SCR_JsonLoadContext loadContext = new SCR_JsonLoadContext();
context.ImportFromString(dataString);
loadContext.ImportFromString(dataString);


string stringValue;
string stringValue;
Line 30: Line 35:


// order does not matter for JSON as it uses key names
// order does not matter for JSON as it uses key names
context.ReadValue("key2", integerValue);
loadContext.ReadValue("key2", integerValue);
context.ReadValue("key1", stringValue);
loadContext.ReadValue("key1", stringValue);
</syntaxhighlight>
</enforce>




Line 39: Line 44:
=== Serialisation ===
=== Serialisation ===


<syntaxhighlight lang="c#">
<enforce>
SCR_BinSaveContext context = new SCR_BinSaveContext();
SCR_BinSaveContext saveContext = new SCR_BinSaveContext();


string stringValue = "data";
string stringValue = "data";
int integerValue = 123;
int integerValue = 123;


context.WriteValue("key1", stringValue);
saveContext.WriteValue("key1", stringValue);
context.WriteValue("key2", integerValue);
saveContext.WriteValue("key2", integerValue);


// process saved data (export, send, save...), in this case data are exported as json string
// process saved data (export, send, save...), in this case data are saved to "file.bin"
dataString = context.ExportToString();
saveContext.SaveToFile("file.bin");
</syntaxhighlight>
</enforce>


=== Deserialisation ===
=== Deserialisation ===


<syntaxhighlight lang="c#">
<enforce>
SCR_BinLoadContext context = new SCR_BinLoadContext();
SCR_BinLoadContext loadContext = new SCR_BinLoadContext();
context.ImportFromString(dataString);
loadContext.LoadFromFile("file.bin");


string stringValue;
string stringValue;
Line 62: Line 67:


// order matters for Binary serialisation, as Binary ignores names
// order matters for Binary serialisation, as Binary ignores names
context.ReadValue("key1", stringValue);
loadContext.ReadValue("key1", stringValue);
context.ReadValue("key2", integerValue);
loadContext.ReadValue("key2", integerValue);
</syntaxhighlight>
</enforce>




Line 72: Line 77:


The following class set to serialise will serialise all its properties.
The following class set to serialise will serialise all its properties.
{{Feature|warning|Data structures that shall be serialised are not allowed to have parameters in their constructor, otherwise they can not be read back.}}


<syntaxhighlight lang="c#">
<enforce>
class MyClass : Managed
class MyClass : Managed
{
{
Line 79: Line 85:
protected string m_sVariable;
protected string m_sVariable;
protected float m_fVariable = 33.3;
protected float m_fVariable = 33.3;
};
}
</syntaxhighlight>
</enforce>


==== NonSerialized ====
==== NonSerialized ====
Adding the {{hl|NonSerialized()}} decorator to a field will make the serialisation ignore it.
Adding the {{hl|NonSerialized()}} decorator to a field will make the serialisation ignore it.
<syntaxhighlight lang="c#">
<enforce>
class MyClass : Managed
class MyClass : Managed
{
{
Line 92: Line 98:
[NonSerialized()]
[NonSerialized()]
protected float m_fVariable = 33.3;
protected float m_fVariable = 33.3;
};
}
</syntaxhighlight>
</enforce>


=== Advanced ===
=== Advanced ===
Line 103: Line 109:
==== SerializationSave ====
==== SerializationSave ====
If an object has the {{hl|SerializationSave}} method defined, the SaveContext will use it and not process object's properties automatically at all.
If an object has the {{hl|SerializationSave}} method defined, the SaveContext will use it and not process object's properties automatically at all.
<syntaxhighlight lang="c#">
<enforce>
class MyClass : Managed
class MyClass : Managed
{
{
Line 110: Line 116:
protected float m_fVariable = 33.3;
protected float m_fVariable = 33.3;


bool SerializationSave(SerializationSaveContext context)
bool SerializationSave(BaseSerializationSaveContext context)
{
{
if (!context.IsValid())
if (!context.IsValid())
return false;
return false;
 
context.WriteValue("theString", m_sVariable);
context.WriteValue("theString", m_sVariable);
context.WriteValue("integer", m_iVariable);
context.WriteValue("integer", m_iVariable);
Line 121: Line 127:
return true;
return true;
}
}
};
}
</syntaxhighlight>
</enforce>


==== SerializationLoad ====
==== SerializationLoad ====
If an object has the {{hl|SerializationLoad}} method defined, the SaveContext will use it and not process object's properties automatically at all.
If an object has the {{hl|SerializationLoad}} method defined, the SaveContext will use it and not process object's properties automatically at all.


<syntaxhighlight lang="c#">
<enforce>
class MyClass : Managed
class MyClass : Managed
{
{
Line 134: Line 140:
protected float m_fVariable = 33.3;
protected float m_fVariable = 33.3;


bool SerializationLoad(SerializationLoadContext context)
bool SerializationLoad(BaseSerializationLoadContext context)
{
{
if (!context.IsValid())
if (!context.IsValid())
Line 145: Line 151:
return true;
return true;
}
}
};
}
</syntaxhighlight>
</enforce>




{{GameCategory|armaR|Modding|Tutorials|Scripting}}
{{GameCategory|armaR|Modding|Tutorials|Scripting}}

Latest revision as of 10:11, 30 September 2024

This page explains serialisation using SCR_JsonSaveContext/SCR_JsonLoadContext and SCR_BinSaveContext/SCR_BinLoadContext.


JSON

Serialisation

SCR_JsonSaveContext saveContext = new SCR_JsonSaveContext(); string stringValue = "data"; int integerValue = 123; saveContext.WriteValue("key1", stringValue); saveContext.WriteValue("key2", integerValue); // process saved data (export, send, save...), in this case data are exported as json string string dataString = saveContext.ExportToString();

Deserialisation

SCR_JsonLoadContext loadContext = new SCR_JsonLoadContext(); loadContext.ImportFromString(dataString); string stringValue; int integerValue; // order does not matter for JSON as it uses key names loadContext.ReadValue("key2", integerValue); loadContext.ReadValue("key1", stringValue);


Binary

Serialisation

SCR_BinSaveContext saveContext = new SCR_BinSaveContext(); string stringValue = "data"; int integerValue = 123; saveContext.WriteValue("key1", stringValue); saveContext.WriteValue("key2", integerValue); // process saved data (export, send, save...), in this case data are saved to "file.bin" saveContext.SaveToFile("file.bin");

Deserialisation

SCR_BinLoadContext loadContext = new SCR_BinLoadContext(); loadContext.LoadFromFile("file.bin"); string stringValue; int integerValue; // order matters for Binary serialisation, as Binary ignores names loadContext.ReadValue("key1", stringValue); loadContext.ReadValue("key2", integerValue);


Object Serialisation

Simple

The following class set to serialise will serialise all its properties.

Data structures that shall be serialised are not allowed to have parameters in their constructor, otherwise they can not be read back.

class MyClass : Managed { protected int m_iVariable = 42; protected string m_sVariable; protected float m_fVariable = 33.3; }

NonSerialized

Adding the NonSerialized() decorator to a field will make the serialisation ignore it.

class MyClass : Managed { protected int m_iVariable = 42; protected string m_sVariable = "Hello there"; [NonSerialized()] protected float m_fVariable = 33.3; }

Advanced

The following methods allow to define a custom serialisation per class. This is useful to avoid saving lengthy yet useless information for loading as well as load values in a certain order.

The NonSerialized decorator is only useful with the simple object serialisation - SerializationSave/SerializationLoad will ignore it.

SerializationSave

If an object has the SerializationSave method defined, the SaveContext will use it and not process object's properties automatically at all.

class MyClass : Managed { protected int m_iVariable = 42; protected string m_sVariable = "Hello there"; protected float m_fVariable = 33.3; bool SerializationSave(BaseSerializationSaveContext context) { if (!context.IsValid()) return false; context.WriteValue("theString", m_sVariable); context.WriteValue("integer", m_iVariable); context.WriteValue("floatingpoint", m_fVariable); return true; } }

SerializationLoad

If an object has the SerializationLoad method defined, the SaveContext will use it and not process object's properties automatically at all.

class MyClass : Managed { protected int m_iVariable = 42; protected string m_sVariable = "Hello there"; protected float m_fVariable = 33.3; bool SerializationLoad(BaseSerializationLoadContext context) { if (!context.IsValid()) return false; context.ReadValue("theString", m_sVariable); context.ReadValue("integer", m_iVariable); context.ReadValue("floatingpoint", m_fVariable); return true; } }