Skip to content

Developer Reference

Jump to bottom
Daemon Forge edited this page Feb 20, 2022 · 53 revisions

Discord

See Developer Reference Discord Wiki Page

Database

Template DB Handler

This is the newest Method in which modders can interact with the Universal API's MongoDB Endpoints providing access to modders to be able to build mods that utilize the Universal API Webservice.

  • oid is the Object ID or Player ID(Can Use Steam64id or GUID)

Steam64ID's are converted to the GUID when it hits the API

class UApiDBHandler<Class T> extends UApiDBHandlerBase

Simple example on how you could use it

autoptr UApiDBHandler<myClass> m_MyModHandler = new UApiDBHandler<myClass>("MyMod", PLAYER_DB); //PLAYER_DB or OBJECT_DB
m_MyModHandler.Save("GUID", myObject);
m_MyModHandler.Load("GUID", player, "CBMyCallBackFunction");

NOTE

All functions return a int matching the call back function id which can be used to cancel the call back using UApi().RequestCallCancel(callId) to stop the call back function from running this is useful as call backs on NULL instances can cause access violations so make sure you track and cancel call backs on object destruction

Saving And Loading Data

Lets you save and load data to the api/database

  • Save Works Server Side Only
  • Load On PlayerDB only works on client for the player the auth key was issued for.
  • Load On ObjectDB works both client and server
int Save(string oid, Class object){}
int Save(string oid, Class object, Class cbInstance, string cbFunction){}

//Load allows you to pass default Object/Json in order to create the object if it doesn't exist (only works on server)
int Load(string oid, Class cbInstance, string cbFunction, string defaultJson = "{}"){}

//Will load onto the passed Object and return it in the Callback function, will also use the inObject as the default if the object doesn't exist in the the database
int Load(string oid, Class cbInstance, string cbFunction, Class inObject){}

Load and Save Callback function

protected void CBMyCallBackFunction(int cid, int status, string oid, myClass data) {
   if ( status == UAPI_SUCCESS ){
      //Do something with data
   }
}

Load Json

Works just like load but returns json string instead of the object incase you want a bit more control on loading

int LoadJson(string oid, Class cbInstance, string cbFunction, string defaultJson = "{}"){}

Load Json Callback Function

protected void CBMyCallBackFunction(int cid, int status, string oid, string data) {
   if ( status == UAPI_SUCCESS ){
      //Do something with data you use 
      autoptr myClass obj;
      if (UApiJSONHandler<myClass>.FromString(data, obj)){
         
      }
   }
}

Transactions

Updates a sub value inside the object in the database then returns the new value only works with floats or ints Sub objects can be used with dot notation aka MySubObject.SubObjectVar Will return status of UAPI_SUCCESS if operations was successful

  • Only works on server
int Transaction(string oid, string element, float value){}
int Transaction(string oid, string element, float value, Class cbInstance, string cbFunction){}
int Transaction(string oid, string element, float value, float min, float max, Class cbInstance, string cbFunction){}

Transactions Call back function

protected void CBMyCallBackFunction(int cid, int status, string oid, UApiTransactionResponse data) {
   if ( status == UAPI_SUCCESS ){
      //Value Updated Successfully
      float newValue = data.Value;
   } else if ( status == UAPI_ERROR ){
      //Failed to update the value 
   } else if ( status == UAPI_NOTFOUND){
      //The item that you tried to update doesn't exist
   }
}

Update Functions

Updates a sub value inside the object in the database, can also use other operations https://github.com/daemonforge/DayZ-UniveralApi/blob/master/_UniversalApi/scripts/1_Core/Constants.c#L30 Values can be in JSON format to update or push elements into arrays

Sub objects can be used with dot notation aka MySubObject.SubObjectVar will return status of UAPI_SUCCESS if operations was successful Only works on server

int Update(string oid, string element, string value, string operation = UpdateOpts.SET){}
int Update(string oid, string element, string value, string operation, Class cbInstance, string cbFunction){} //Return's Type UApiUpdateResponse

Update Call back function

protected void CBMyCallBackFunction(int cid, int status, string oid, UApiUpdateResponse data) {
   if ( status == UAPI_SUCCESS ){
      //Value Updated Successfully
   }
}

Queries

Queries allow you to search the database for you objects and return them in an array. Uses MongoDB Queries https://docs.mongodb.com/manual/tutorial/query-documents/

  • Query Example "{ \"MyVar\": 3 }" would return all objects that have MyVar = 3
  • Query Example "{ \"MyVar\": { \"$gte\": 5} }" would return all objects that have MyVar = 5 or higher
  • Query Example "{ \"MyTStrringArray\": \"somevalue\" }" would return all objects that have a value of 'somevalue' inside the array
  • Query Example "{ \"MySubObject.SubVar\": 3 }" would return all objects that have a SubVar = 3 inside a sub object this also works if the sub object was an array
  • Only works on server for Player DB
  • Works server and client on ObjectDB
int Query(UApiQueryBase query, Class cbInstance, string cbFunction){}
int Query(string query, Class cbInstance, string cbFunction){}

Call Back Function

protected void CBMyCallBackFunction(int cid, int status, string oid/* oid will be empty */, UApiQueryResult<myClass> data) {
   if ( status == UAPI_SUCCESS ){
      //Do something with data
      array<autoptr myClass> results = data.GetResults();
   } else if (status == UAPI_EMPTY){ // no results
  }
}

Database JSON Api

Some basic documentation for the current Updated features.

There are two main ways to receive the call backs

//Client side is read only server side for read and write
UApi().db(PLAYER_DB).   //Client Side reads to only their own GUID
UApi().db(OBJECT_DB).    //Client Side reads to all data

There are two ways to handle the callbacks the main way being specifying the Instance and Function which by default returns the json string using the JSON Callback Function or to use a UApiCallback UApiCallback< T >(cbInstance, cbFunction) where T is the class that the object will be convert to and will pass that class instead of the string.

Saving Json to API

int Save(string mod, string oid, string jsonString) {}
int Save(string mod, string oid, string jsonString, Class cbInstance, string cbFunction) {}
int Save(string mod, string oid, string jsonString, UApiCallbackBase cb) {}

Loading Json From API

int Load(string mod, string oid, UApiCallbackBase cb, string jsonString = "{}") {}
int Load(string mod, string oid, Class cbInstance, string cbFunction, string jsonString = "{}") {}

Query from the API

int Query(string mod, UApiQueryBase query, UApiCallbackBase cb) {}
int Query(string mod, UApiQueryBase query, Class cbInstance, string cbFunction) {}

Increment a value on the API

int Increment(string mod, string oid, string element, float value = 1){}

Runs Transaction

Plan to eventually have ability to set min and max values.

int Transaction(string mod, string oid, string element, float value) {}
int Transaction(string mod, string oid, string element, float value, UApiCallbackBase cb) {}
int Transaction(string mod, string oid, string element, float value, Class cbInstance, string cbFunction) {}

Updates an element in the database

int Update(string mod, string oid, string element, string value, string operation = UpdateOpts.SET) {}
int Update(string mod, string oid, string element, string value, string operation, UApiCallbackBase cb) {}
int Update(string mod, string oid, string element, string value, string operation, Class cbInstance, string cbFunction) {}

Globals Json API

Globals are used when your mod might just need one thing saved just for the mod, or more commonly used for configs if you want to make sure the config matches across all servers.

UApi().globals().
int Save(string mod, string jsonString) {}
int Save(string mod, string jsonString, Class cbInstance, string cbFunction) {}
int Save(string mod, string jsonString, UApiCallbackBase cb) {}

int Load(string mod, Class cbInstance, string cbFunction, string jsonString = "{}") {}
int Load(string mod, UApiCallbackBase cb, string jsonString = "{}") {}
	
int Increment(string mod, string element, float value = 1){}
	
int Transaction(string mod, string element, float value) {}
int Transaction(string mod, string element, float value, Class cbInstance, string cbFunction) {}
int Transaction(string mod, string element, float value, UApiCallbackBase cb) {}

//This will change to match 
int Update(string mod, string element, string value, string operation = UpdateOpts.SET, Class instance = NULL, string function = "") {}

JSON Callback Function

/* 
cid - is the call ID returned when the function request was called
status - returns the status of the call UAPI_SUCCESS, UAPI_EMPTY, UAPI_TIMEOUT, UAPI_CLIENTERROR, UAPI_SERVERERROR (for most call backs)
oid - is the Object ID or Player GUID of the requested player or object or in some cases the Id you specify if the request doesn't require an ID
data - is the data in a string format
*/
void CallbackFunction(int cid, int status, string oid, string data){
   if (status == UAPI_SUCCESS){
      YourClassName dataload;
      if (UApiJSONHandler<YourClassName>.FromString(data, dataload)){
         //Do you thing
      } else {
         Error("Failed to convert data to object");
      }
   } else if (status == UAPI_EMPTY) {
      //Response from API was empty meaning object does exist
   } else if (status == UAPI_TIMEOUT) {
      //Most likely the API is down
   } else {
      //Some Other Error Happened
   }
}

Misc APIs

NOTE

Quantum Random

This uses the ANU Quantum Random Number API to generate truly random numbers I also pre generate numbers as soon as the Mod is ready for modders to they don't have to worry about having to worry about call backs and can use functions they are familiar with.

4096 numbers are generated on both client and server, server side every 10 minutes it will check to see if its below 2000 numbers and generate more. client side its slower at every 25 minutes when the the client renews it's auth token

Math Functions

/*
QRandom
Returns a random number between int.MIN and int.MAX */
int rnd = Math.QRandom();

/*
QRandomInt
Returns a random number between the values the min and max values due to the math I use I recommend not using differences of more than 10,000,000*/
int rnd = Math.QRandomInt(int min, int max);

/*
QRandomFloat
Returns a random number between the values the min and max values I recommend not using differences of more than 2,000,000,000*/
float rnd = Math.QRandomFloat(float min, float max);

/*
QRandomFlip
Returns Random bool (true or false)*/
bool rnd = Math.QRandomFlip();

/*
QRandomRemaining
A way to check how many numbers are remaining encase you think you might go past the limits*/
int remaining = Math.QRandomRemaining();

Request your own random numbers

You can always check and refresh the Math Random stock using UApi().CheckAndRenewQRandom()

//Gets an array of random number from  0 to 65535 returns `UApiRandomNumberResponse`
int UApi().api().RandomNumbers(int count/*Max 2048*/, Class cbInstance, string cbFunction, string oid = "", bool ReturnString = false){}
//Gets an array of random number from  -2147483647 to 2147483647 returns `UApiRandomNumberResponse`
int UApi().api().RandomNumbersFull(int count/*Max 4096*/, Class cbInstance, string cbFunction, bool ReturnString = false, string oid = ""){}

Random Number Callback function

protected void CBMyCallBackFunction(int cid, int status, string oid, UApiRandomNumberResponse data){
   if (status == UAPI_SUCCESS){
      //Random Numbers Returned
   }
}

Translation

By default uses my libre translate api https://translate.daemonforge.dev/ You can setup your own with https://github.com/LibreTranslate/LibreTranslate or use Microsoft Translate API These are configured on the WebService side. as a modder you can just use the functions, Microsoft's is better and more accurate and has a free tier The microsoft API allows multiple languages

int UApi().api().Translate(string Text, string To, string From, Class cbInstance, string cbFunction, string oid = "", bool ReturnString = false){}
/* If you know the Web Service is using the Microsoft API it can auto detect the from and translate to multiple languages in one request */
int UApi().api().Translate(string Text, TStringArray To, Class cbInstance, string cbFunction, string oid = "", bool ReturnString = false){}

Translation Callback function

protected void CBMyCallBackFunction(int cid, int status, string oid, UApiTranslationResponse data){
   if (status == UAPI_SUCCESS){
      //Translation Response
   }
}

Toxicity

Uses Tensorflow Toxicity Classifier

int UApi().api().Toxicity(string text, Class cbInstance, string cbFunction, string oid = "", bool ReturnString = false){}

Toxicity Callback function

protected void CBMyCallBackFunction(int cid, int status, string oid, UApiToxicityResponse data){
   if (status == UAPI_SUCCESS){
      //Translation Response
   }
}

Steam Query

Checks performance a steam query on the server

int UApi().api().SteamQuery(string ip, string queryPort, Class cbInstance, string cbFunction, string oid = "", bool ReturnString = false){}

Steam Query Callback function

protected void CBMyCallBackFunction(int cid, int status, string oid, UApiServerStatus data){
   if (status == UAPI_SUCCESS){
      //Translation Response
   }
}

QnA

Need Account and Api Keys from qnamaker.ai

Clone this wiki locally