DataPacks (AMX Mod X Scripting) - Revision history

Arkshine: Fixed typos

2017-06-18T14:43:56Z

Fixed typos

Arkshine at 22:55, 17 June 2017

2017-06-17T22:55:11Z

Arkshine: Adjusted few things

2017-06-17T20:11:06Z

Adjusted few things

Arkshine: Added DataPack documentation

2017-06-17T19:24:41Z

Added DataPack documentation

New page

__FORCETOC__
{{Languages|{{PAGENAME}}}}

== About ==

Datapacks provide a way to store and move around arbitrary amounts (and types) of data in AMX Mox X, available from [https://github.com/alliedmodders/amxmodx/blob/master/plugins/include/datapack.inc datapack.inc]. <br />
Data is packed into a single cell value - the {{tt|DataPack}} handle. This handle can be passed around more easily, can be returned by functions and can simulate advanced concepts like string consummation.

== Usage ==

=== Creating & Disposing ===

:{{margin|20px 0 15px 0|{{tt|{{color|green|DataPack}}:CreateDataPack()|opt=large}}}}
:: Creates a new datapack.

::{{alert|info|Return:|New datapack handle, which must be freed via {{tt|DestroyDataPack|opt=nobg}}.|opt=full-border}}
::{{alert|danger|Important:|Plugins are responsible for freeing all datapack handles they acquire. Failing to free handles will result in the plugin and AMXX leaking memory.|opt=full-border}}
::{{alert|success|Example:|{{tt|new const {{color|green|DataPack}}:handle <nowiki>=</nowiki> CreateDataPack();|opt=nobg}}|opt=full-border}}

:{{margin|35px 0 15px 0|{{tt|DestroyDataPack(&{{color|green|DataPack}}:pack)|opt=large}}}}
::Destroys the datapack and frees its memory.

::{|
|-
| {{tt|pack}} || {{ns}} Datapack handle to free.
|-
|}

::{{alert|info|Note:|{{tt|pack|opt=nobg}} will be reset to 0.|opt=full-border}}
::{{alert|success|Example:|{{tt|DestroyDataPack(pack);|opt=nobg}}|opt=full-border}}

=== Resetting ===

:{{margin|20px 0 15px 0|{{tt|ResetPack({{color|green|DataPack}}:pack, {{color|green|bool}}:clear <nowiki>=</nowiki> false)|opt=large}}}}
::Resets the datapack read/write position to the start.

::{|
|-
| {{tt|clear}} || {{ns}} If true, clears the contained data.
|-
|}

::{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
::{{alert|success|Example:|{{tt|ResetPack(pack);|opt=nobg}}|opt=full-border}}

=== Writing data ===

:{{margin|20px 0 15px 0|{{tt|WritePackCell({{color|green|DataPack}}:pack, {{color|green|any}}:cell)|opt=large}}}}
:: Packs a cell value into a datapack.

::{{alert|success|Example:|{{tt|WritePackString(pack, 42);|opt=nobg}}|opt=full-border}}

:{{margin|35px 0 15px 0|{{tt|WritePackFloat({{color|green|DataPack}}:pack, {{color|green|Float}}:cell)|opt=large}}}}
:: Packs a float value into a datapack.

::{{alert|success|Example:|{{tt|WritePackString(pack, 13.36);|opt=nobg}}|opt=full-border}}

:{{margin|35px 0 15px 0|{{tt|WritePackString({{color|green|DataPack}}:pack, const str[])|opt=large}}}}
:: Packs a string value into a datapack.

::{{alert|info|Return:|Length of copied string.|opt=full-border}}
::{{alert|success|Example:|{{tt|new const length <nowiki>=</nowiki> WritePackString(pack, "Hello world!");|opt=nobg}}|opt=full-border}}

=== Reading data ===

:{{margin|20px 0 15px 0|{{tt|{{color|green|bool}}:IsPackEnded({{color|green|DataPack}}:pack)|opt=large}}}}
:: Returns if the datapack has reached its end and no more data can be read.

::{{alert|info|Return:|True if datapack has reached the end, false otherwise.|opt=full-border}}
::{{alert|success|Example:|{{tt|if (IsPackEnded(pack)) {}|opt=nobg}}|opt=full-border}}

:{{margin|20px 0 15px 0|{{tt|{{color|green|any}}:ReadPackCell({{color|green|DataPack}}:pack)|opt=large}}}}
:: Reads a cell from a Datapack.

::{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
::{{alert|info|Return:|Cell value.|opt=full-border}}
::{{alert|success|Example:|{{tt|new value <nowiki>=</nowiki> ReadPackString(pack);|opt=nobg}}|opt=full-border}}

:{{margin|35px 0 15px 0|{{tt|{{color|green|Float}}:ReadPackFloat({{color|green|DataPack}}:pack)|opt=large}}}}
:: Reads a float from a Datapack.

::{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
::{{alert|info|Return:|Float value.|opt=full-border}}
::{{alert|success|Example:|{{tt|new {{color|green|Float}}:value <nowiki>=</nowiki> ReadPackString(pack);|opt=nobg}}|opt=full-border}}

:{{margin|35px 0 15px 0|{{tt|ReadPackString({{color|green|DataPack}}:pack, buffer[], maxlen)|opt=large}}}}
:: Reads a string from a Datapack.

::{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
::{{alert|info|Return:|Number of cells written to buffer.|opt=full-border}}
::{{alert|success|Example:|{{tt|new buffer[32];<br/>new const length <nowiki>=</nowiki> ReadPackString(pack, buffer, charsmax(buffer));|opt=nobg}}|opt=full-border}}

=== Managing position ===

:{{margin|20px 0 15px 0|{{tt|{{color|green|DataPackPos}}:GetPackPosition({{color|green|DataPack}}:pack)|opt=large}}}}
:: Returns the datapack read/write position.

::{{alert|info|Return:|Position in the datapack, only usable with calls to {{tt|SetPackPosition|opt=nobg}}.|opt=full-border}}
::{{alert|success|Example:|{{tt|new const {{color|green|DataPackPos}}:position <nowiki>=</nowiki> GetPackPosition(pack);|opt=nobg}}|opt=full-border}}

:{{margin|20px 0 15px 0|{{tt|SetPackPosition({{color|green|DataPack}}:pack, {{color|green|DataPackPos}}:position)|opt=large}}}}
:: Sets the datapack read/write position.

::{{alert|warning|Attention:|This should only ever be used with (known to be valid) positions returned by {{tt|GetPackPosition|opt=nobg}}. It is not possible for plugins to safely compute datapack positions.|opt=full-border}}
::{{alert|success|Example:|{{tt|SetPackPosition(pack, position);|opt=nobg}}|opt=full-border}}

== Example ==

<pawn>
foo()
{
// Creating
new const DataPack:pack = CreateDataPack();

// Writing
WritePackCell(pack, refCell);
WritePackFloat(pack, refFloat);
WritePackString(pack, refString);

// Reset before reading
ResetPack(pack);
server_print("Datapack is readable: %s", !IsPackEnded(pack) ? "yes" : "no");

// Reading
new cellValue = ReadPackCell(pack);
new Float:floatValue = ReadPackFloat(pack);
new buffer[32];
ReadPackString(pack, buffer, charsmax(buffer));
server_print("cellValue = %d, floatValue = %f, buffer = %s", cellValue, floatValue, buffer)
server_print("Datapack is no more readable: %s", IsPackEnded(pack) ? "yes" : "no");

// Clear all data
ResetPack(pack, .clear = true);
server_print("Datapack is empty: %s", IsPackEnded(pack) ? "yes" : "no");

// Disposing
DestroyDataPack(pack);
}
</pawn>

[[Category:Scripting_(AMX_Mod_X)]]

@@ Line 50: / Line 50: @@
 : Packs a cell value into a datapack.
-:{{alert|success|Example:|{{tt|WritePackString(pack, 42);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|WritePackCell(pack, 42);|opt=nobg}}|opt=full-border}}
 {{margin|35px 0 15px 0|{{tt|WritePackFloat({{color|green|DataPack}}:{{h:title||pack}}, {{color|green|Float}}:{{h:title||val}})|opt=large}}}}
 : Packs a float value into a datapack.
-:{{alert|success|Example:|{{tt|WritePackString(pack, 13.36);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|WritePackFloat(pack, 13.36);|opt=nobg}}|opt=full-border}}
 {{margin|35px 0 15px 0|{{tt|WritePackString({{color|green|DataPack}}:{{h:title||pack}}, const {{h:title||str}}[])|opt=large}}}}
@@ Line 76: / Line 76: @@
 :{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
 :{{alert|info|Return:|Cell value.|opt=full-border}}
-:{{alert|success|Example:|{{tt|new value <nowiki>=</nowiki> ReadPackString(pack);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|new value <nowiki>=</nowiki> ReadPackCell(pack);|opt=nobg}}|opt=full-border}}
 {{margin|35px 0 15px 0|{{tt|{{color|green|Float}}:ReadPackFloat({{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
@@ Line 83: / Line 83: @@
 :{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
 :{{alert|info|Return:|Float value.|opt=full-border}}
-:{{alert|success|Example:|{{tt|new {{color|green|Float}}:value <nowiki>=</nowiki> ReadPackString(pack);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|new {{color|green|Float}}:value <nowiki>=</nowiki> ReadPackFloat(pack);|opt=nobg}}|opt=full-border}}
 :{{margin|35px 0 15px 0|{{tt|ReadPackString({{color|green|DataPack}}:{{h:title||pack}}, {{h:title||buffer}}[], {{h:title||maxlen}})|opt=large}}}}

@@ Line 12: / Line 12: @@
 === Creating & Disposing ===
-:{{margin|20px 0 15px 0|{{tt|{{color|green|DataPack}}:CreateDataPack()|opt=large}}}}
+{{margin|20px 0 15px 0|{{tt|{{color|green|DataPack}}:CreateDataPack()|opt=large}}}}
-:: Creates a new datapack.
+: Creates a new datapack.
-::{{alert|info|Return:|New datapack handle, which must be freed via {{tt|DestroyDataPack|opt=nobg}}.|opt=full-border}}
+:{{alert|info|Return:|New datapack handle, which must be freed via {{tt|DestroyDataPack|opt=nobg}}.|opt=full-border}}
-::{{alert|danger|Important:|Plugins are responsible for freeing all datapack handles they acquire. Failing to free handles will result in the plugin and AMXX leaking memory.|opt=full-border}}
+:{{alert|danger|Important:|Plugins are responsible for freeing all datapack handles they acquire. Failing to free handles will result in the plugin and AMXX leaking memory.|opt=full-border}}
-::{{alert|success|Example:|{{tt|new const {{color|green|DataPack}}:handle <nowiki>=</nowiki> CreateDataPack();|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|new const {{color|green|DataPack}}:handle <nowiki>=</nowiki> CreateDataPack();|opt=nobg}}|opt=full-border}}
-:{{margin|35px 0 15px 0|{{tt|DestroyDataPack(&{{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
+{{margin|35px 0 15px 0|{{tt|DestroyDataPack(&{{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
-::Destroys the datapack and frees its memory.
+:Destroys the datapack and frees its memory.
-::{|
+:{|
 |-
 | {{tt|pack}} || {{ns}} Datapack handle to free.
@@ Line 28: / Line 28: @@
 |}
-::{{alert|info|Note:|{{tt|pack|opt=nobg}} will be reset to 0.|opt=full-border}}
+:{{alert|info|Note:|{{tt|pack|opt=nobg}} will be reset to 0.|opt=full-border}}
-::{{alert|success|Example:|{{tt|DestroyDataPack(pack);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|DestroyDataPack(pack);|opt=nobg}}|opt=full-border}}
 === Resetting ===
-:{{margin|20px 0 15px 0|{{tt|ResetPack({{color|green|DataPack}}:{{h:title||pack}}, {{color|green|bool}}:{{h:title||clear}} <nowiki>=</nowiki> false)|opt=large}}}}
+{{margin|20px 0 15px 0|{{tt|ResetPack({{color|green|DataPack}}:{{h:title||pack}}, {{color|green|bool}}:{{h:title||clear}} <nowiki>=</nowiki> false)|opt=large}}}}
-::Resets the datapack read/write position to the start.
+:Resets the datapack read/write position to the start.
-::{|
+:{|
 |-
 | {{tt|clear}} || {{ns}} If true, clears the contained data.
@@ Line 42: / Line 42: @@
 |}
-::{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
+:{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
-::{{alert|success|Example:|{{tt|ResetPack(pack);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|ResetPack(pack);|opt=nobg}}|opt=full-border}}
 === Writing data ===
-:{{margin|20px 0 15px 0|{{tt|WritePackCell({{color|green|DataPack}}:{{h:title||pack}}, {{color|green|any}}:{{h:title||cell}})|opt=large}}}}
+{{margin|20px 0 15px 0|{{tt|WritePackCell({{color|green|DataPack}}:{{h:title||pack}}, {{color|green|any}}:{{h:title||cell}})|opt=large}}}}
-:: Packs a cell value into a datapack.
+: Packs a cell value into a datapack.
-::{{alert|success|Example:|{{tt|WritePackString(pack, 42);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|WritePackString(pack, 42);|opt=nobg}}|opt=full-border}}
-:{{margin|35px 0 15px 0|{{tt|WritePackFloat({{color|green|DataPack}}:{{h:title||pack}}, {{color|green|Float}}:{{h:title||val}})|opt=large}}}}
+{{margin|35px 0 15px 0|{{tt|WritePackFloat({{color|green|DataPack}}:{{h:title||pack}}, {{color|green|Float}}:{{h:title||val}})|opt=large}}}}
-:: Packs a float value into a datapack.
+: Packs a float value into a datapack.
-::{{alert|success|Example:|{{tt|WritePackString(pack, 13.36);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|WritePackString(pack, 13.36);|opt=nobg}}|opt=full-border}}
-:{{margin|35px 0 15px 0|{{tt|WritePackString({{color|green|DataPack}}:{{h:title||pack}}, const {{h:title||str}}[])|opt=large}}}}
+{{margin|35px 0 15px 0|{{tt|WritePackString({{color|green|DataPack}}:{{h:title||pack}}, const {{h:title||str}}[])|opt=large}}}}
-:: Packs a string value into a datapack.
+: Packs a string value into a datapack.
-::{{alert|info|Return:|Length of copied string.|opt=full-border}}
+:{{alert|info|Return:|Length of copied string.|opt=full-border}}
-::{{alert|success|Example:|{{tt|new const length <nowiki>=</nowiki> WritePackString(pack, "Hello world!");|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|new const length <nowiki>=</nowiki> WritePackString(pack, "Hello world!");|opt=nobg}}|opt=full-border}}
 === Reading data ===
-:{{margin|20px 0 15px 0|{{tt|{{color|green|bool}}:IsPackEnded({{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
+{{margin|20px 0 15px 0|{{tt|{{color|green|bool}}:IsPackEnded({{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
-:: Returns if the datapack has reached its end and no more data can be read.
+: Returns if the datapack has reached its end and no more data can be read.
-::{{alert|info|Return:|True if datapack has reached the end, false otherwise.|opt=full-border}}
+:{{alert|info|Return:|True if datapack has reached the end, false otherwise.|opt=full-border}}
-::{{alert|success|Example:|{{tt|if (IsPackEnded(pack)) {}|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|if (IsPackEnded(pack)) {}|opt=nobg}}|opt=full-border}}
-:{{margin|20px 0 15px 0|{{tt|{{color|green|any}}:ReadPackCell({{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
+{{margin|20px 0 15px 0|{{tt|{{color|green|any}}:ReadPackCell({{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
-:: Reads a cell from a Datapack.
+: Reads a cell from a Datapack.
-::{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
+:{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
-::{{alert|info|Return:|Cell value.|opt=full-border}}
+:{{alert|info|Return:|Cell value.|opt=full-border}}
-::{{alert|success|Example:|{{tt|new value <nowiki>=</nowiki> ReadPackString(pack);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|new value <nowiki>=</nowiki> ReadPackString(pack);|opt=nobg}}|opt=full-border}}
-:{{margin|35px 0 15px 0|{{tt|{{color|green|Float}}:ReadPackFloat({{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
+{{margin|35px 0 15px 0|{{tt|{{color|green|Float}}:ReadPackFloat({{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
-:: Reads a float from a Datapack.
+: Reads a float from a Datapack.
-::{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
+:{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
-::{{alert|info|Return:|Float value.|opt=full-border}}
+:{{alert|info|Return:|Float value.|opt=full-border}}
-::{{alert|success|Example:|{{tt|new {{color|green|Float}}:value <nowiki>=</nowiki> ReadPackString(pack);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|new {{color|green|Float}}:value <nowiki>=</nowiki> ReadPackString(pack);|opt=nobg}}|opt=full-border}}
 :{{margin|35px 0 15px 0|{{tt|ReadPackString({{color|green|DataPack}}:{{h:title||pack}}, {{h:title||buffer}}[], {{h:title||maxlen}})|opt=large}}}}
-:: Reads a string from a Datapack.
+: Reads a string from a Datapack.
-::{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
+:{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
-::{{alert|info|Return:|Number of cells written to buffer.|opt=full-border}}
+:{{alert|info|Return:|Number of cells written to buffer.|opt=full-border}}
-::{{alert|success|Example:|{{tt|new buffer[32];<br/>new const length <nowiki>=</nowiki> ReadPackString(pack, buffer, charsmax(buffer));|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|new buffer[32];<br/>new const length <nowiki>=</nowiki> ReadPackString(pack, buffer, charsmax(buffer));|opt=nobg}}|opt=full-border}}
 === Managing position ===
-:{{margin|20px 0 15px 0|{{tt|{{color|green|DataPackPos}}:GetPackPosition({{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
+{{margin|20px 0 15px 0|{{tt|{{color|green|DataPackPos}}:GetPackPosition({{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
-:: Returns the datapack read/write position.
+: Returns the datapack read/write position.
-::{{alert|info|Return:|Position in the datapack, only usable with calls to {{tt|SetPackPosition|opt=nobg}}.|opt=full-border}}
+:{{alert|info|Return:|Position in the datapack, only usable with calls to {{tt|SetPackPosition|opt=nobg}}.|opt=full-border}}
-::{{alert|success|Example:|{{tt|new const {{color|green|DataPackPos}}:position <nowiki>=</nowiki> GetPackPosition(pack);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|new const {{color|green|DataPackPos}}:position <nowiki>=</nowiki> GetPackPosition(pack);|opt=nobg}}|opt=full-border}}
-:{{margin|20px 0 15px 0|{{tt|SetPackPosition({{color|green|DataPack}}:{{h:title||pack}}, {{color|green|DataPackPos}}:{{h:title||position}})|opt=large}}}}
+{{margin|20px 0 15px 0|{{tt|SetPackPosition({{color|green|DataPack}}:{{h:title||pack}}, {{color|green|DataPackPos}}:{{h:title||position}})|opt=large}}}}
-:: Sets the datapack read/write position.
+: Sets the datapack read/write position.
-::{{alert|warning|Attention:|This should only ever be used with (known to be valid) positions returned by {{tt|GetPackPosition|opt=nobg}}. It is not possible for plugins to safely compute datapack positions.|opt=full-border}}
+:{{alert|warning|Attention:|This should only ever be used with (known to be valid) positions returned by {{tt|GetPackPosition|opt=nobg}}. It is not possible for plugins to safely compute datapack positions.|opt=full-border}}
-::{{alert|success|Example:|{{tt|SetPackPosition(pack, position);|opt=nobg}}|opt=full-border}}
+:{{alert|success|Example:|{{tt|SetPackPosition(pack, position);|opt=nobg}}|opt=full-border}}
 == Example ==