Difference between revisions of "Scripting Documentation Guide"

From DCS World Wiki - Hoggitworld.com
m (1 revision imported)
(No difference)

Revision as of 00:12, 12 April 2018

This is a guide to explain to a minor extent how functions work, but this guide is mostly focused on how the scripting documentation on this wiki is organized.

Guide Format

This guide utilizes a color coded breakdown of different parts of each function.

ReturnedValueType, … functionName( RequiredVariableType RequiredVariableName, … , OptionalVariableType OptionalVariableName, … )

Return Variable Type Name of Function Required Input Variables Optional Input Variables
ReturnedValueType, … functionName() RequiredVariableType RequiredVariableName, … OptionalVariableType OptionalVariableName, …
This is the value type that is returned when the function is run. The return variable is always colored in ORANGE Typical values are:
boolean (true/false)
table
string
number
nothing (literally nothing is returned) 
This is the name of the scripting function. It is case sensitive. Required input variables are defined as the bare minimum variables needed for the function to work correctly. All required variables are colored in BLUE Optional input variables are listed after the required variables and are colored in GREEN. Most functions should be programmed so that not all optional values are required. Optional values that are not needed should simply be listed as nil. For example mist.groupRandomDistSelf
mist.groupRandomDistSelf('myGroup2', 6000, nil, 270)
Required variable type name in bold description of what it is used for in italics Required variable type name in bold description of what it is used for in italics

The order of the values must remain the same. Think of each function as the following:

myFunction(inputValue1, inputValue2, inputValue3, inputValue4, etc)


The minimum number of variables is dependent on the number of required variables. For example mist.groupToPoint has 2 required variables and 4 optional variables. The following are each a valid function call.

mist.groupToPoint('myGroup', 'myZone')
mist.groupToPoint('myGroup', 'myZone', nil, 35, 30)
mist.groupToPoint('myGroup', 'myZone', 'cone', nil, nil, true)
mist.groupToPoint('myGroup', 'myZone', nil, nil, nil, true)

Table Input Variables

Input values that are tables have their own requirements. A table is similar to the above variables, however each table entry has a specific name instead of following a specific order.


Function Page Guide

Each function page will look something like this.


functionName

Added with: Version of game or Custom Script in which the this function was added.
Description
A short description of what the function does
Syntax
ReturnedValueType, … functionName(RequiredVariableDataType RequiredVariableName ,type name , OptionalVariableType OptionalVariableName )
Valid Input Values:
In this space is a description of each variable and what it does. This section is not color coded. Typically it will look like this:

RequiredVariableName1 = 'myGroup' (an actual example)

or

RequiredVariableName1 = string of groupName (description of what the value should be)


If the variables are a table there is usually a description or example of what should be in the table. If a generic table name of "vars" is used this section will usually be accompanied by the following data:


vars tables have the following recognized fields( required entries in blue, optional in green):

 vars = 
 {
 reqTableEntryName1 = reqDataType1 reqTableEntryName1, 
 reqTableEntryName2 = reqDataType2 reqTableEntryName2, 
 reqTableEntryName3 = reqDataType3 reqTableEntryName3,
 optionalTableEntryName1 = optionalDataType1 optionalTableEntryName1, 
 optionalTableEntryName2 = optionalDataType2 optionalTableEntryName2,
 }

reqTableEntryName1 short description of what this entry needs to be

reqTableEntryName2 short description of what this entry needs to be

reqTableEntryName3 short description of what this entry needs to be

optionalTableEntryName1 short description of what this entry needs to be

optionalTableEntryName2 short description of what this entry needs to be

Return value:
ReturnedValueType, …
Return example:
Simple example of what is returned.
Usage Examples:
 Coding example of how to use the script for a practical but simple implementation
 do
  local myValue = myFunction('reqVariable1', ReqVars, 'optionalValue2')
 end

Notes:
Assorted notes will go into this section. Generally anything about how the function might have changed from one version to another. Also present in this section could be a list of other functions that this function will utilize.
Related Functions
Links to related functions will be here. Generally listed by approximate category or object class functions.

Scripting Engine

MIST Root Page