2. Base Functions (For your own Squirrel scripts)

The DScript comes with a range of some global base functions so they are not tied to a script class and can be used everywhere inside your script.

DScript 0.28b Squirrel Features

These features/functions specified here are globally available to whom has the DScript.nut file and are not bind to the DBaseTrap.

DGetParam("FullParameterName",DefaultValue, Table=YourDesignNote ,adv=0) Returns the parameter specified in the Design Note if none is present the DefaultValue is used instead. The 3rd parameter is where the function actually looks for the parameters. Most of the time it will be the standard Design Note (userparams() ). But you can also check other table-like structures like classes. The valid Value will then be checked by:

DCheckString(r,adv) This function analyzes the given string r and performs the operator checks as listed in DBaseTrap. @,&,[me],+ ... Each found object/value will be stored in an array. If adv = true the whole array will be returned and can be used for foreach (t in array){ ... }. Else (default: adv=false) only a single value will be returned.

DGetStringParam("FullParameterName",DefaultValue, String ,adv=0) Identically to DGetParam but that this function takes strings which are formatted like this: "ParameterName=Value;Key=Value2". DCheckString is then called as well.

DGetAllDescendants(Archetype,array) Returns all concrete descendants of an archetype and all other inherited archetypes in an array. The function must be given an array to work with all found objects will be added to that array.

DCountCapaCheck(Script Name, Design Note, true/false for On/Off) and DCapacitorCheck These handle partly the Count and Capacitor parameters for the DBaseTrap and then call the DoOn/Off functions. As they are global functions I noted them here but they will not work as standalone.

DArrayToString(Array , Seperator ="+") converts an array to a string with the character defined by Seperator between them, default +. The reverse to string split.

DSendMessage(Target, Message) (need extends DRelayTrap) Will send a single Message to a single target and check if the message should be a Stim. If so it will stimulate the Target.

DRelayMessages("On" or "Off", DesignNote) (need extends DRelayTrap) Will relay the Messages in [ScriptName]T[On/Off] to the objects [ScriptName][On/Off]TDest via DSendMessage.

---

DSetTimerData(name, delay,...[data you want to attach]) returns timer_handle DSetTimerDataTo(To,name,delay,...) same as above but sent to To instead of self. DGetTimerData(msgdata,KeyValue=false) returns an Array with your data.

The functions start a timer with multiple data attachments which can be returned later in an array out of the message().data. This Data is save game compatible!

---

But now let me explain why these functions are important/useful: If there is a time gap between two actions, there is always the problem how to safely carry over data. The (human) player could save and reload the game in the meantime and all non persistent data will be whipped as new script instances are recreated. The relevant persistent data are Script Data set with SetData(k,v), QVars and timers.

I don't know it but I think NV came up with something similar so I take an NVRelayTrap as an example: which inverts the message and sends it twice back to the sender (with a delay). So now we got two objects sending a TurnOn and TurnOff to the Trap and here's the problem a) after the delay how to know which object sent the message? b) What was the message again? and c) how to know if it's first message and needs to be send again? We would need to save three values. But SetOneShotTimer only has one data slot. The second message would override the first SetData or QVar. Well you could store multiple ScriptData with a prefix and save that prefix in the timer data slot, but I think memory wise that's not the best solution, also it would increase very fast if you need to transfer even more data.

---

Data can be stored and retrieved in a fixed order (KeyValue=false) or in a not sorted manner with keyword before them (KeyValue=true), for the later see below. As an example for the sorted manner if you know the first data is always the source and the second the are repeats left. The returned Array will be [source Obj ID, Repeats left] And you can use array[0],array[1] to grab your data.

If there are other data you want to store but for example some are optional you can store them via key=value,key2=value2,... Now if you use KeyValue=true the array will look like this [key,value,key2,value2] and you can search and find your values like this: Code:

local array=DGetTimerData(message().data,true)
local key = array.find(-->Your Key<--);
local value =0

if (key!=null)
     {value =array[key+1]}

Take a look at the DDrunkPlayerTrap script how I made use of that.