Translators: API Dictionary - UA-ScriptEase/scriptease GitHub Wiki

#Overview At its core, the API Dictionary is an XML listing of all possible API calls, types, and slots that can be used in the particular language.

The apidictionary.xml file should adhere to the schema in resources/schema/ApiDictionarySchema.xsd. An example blank file looks something like this:

<APIDictionary name="" author="" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:noNamespaceSchemaLocation='../../../scriptease2/scriptease/resources/schema/ApiDictionarySchema.xsd'>
<Types/>
<Slots defaultFormat="file"/>
<Causes/>
<Effects/>
<Descriptions/>
<TypeConverters/>

The attributes xmlns:xsi and xsi:noNamespaceSchemaLocation are not mandatory, but they allow Eclipse to validate the XML for you (right click->validate), which is faster than running ScriptEase.

#ScriptIts ScriptIts are defined in the API Dictionary to provide hooks to the game's API and to define custom user calls. A ScriptIt has the ability to generate more than a single function by having more than a single CodeBlock.

ScriptIt:
Name
Labels
Children
CodeBlocks

#CodeBlocks CodeBlocks are the container for all of the information required to create a function. They have a type, list of parameters, subject, slot, and list of code generation directives. There is a one-to-one mapping between CodeBlock and function call. They reside in ScriptIts, which may have one or more CodeBlocks. There are two kinds of CodeBlocks: CodeBlockSources and CodeBlockReferences. The Sources exist in the API dictionary, so that we always get code directly from the API dictionary. References live in Stories, and point to Sources where they forward their data requests.

###Content Display Name: The display name is required and is what may be displayed to the user when selecting the appropriate DoIt
Code Custom code that the Translator author wishes to be the code body for the function call
Argument The arguments (KnowIts) needed by the function call. They are optional since there are many functions which take no arguments
Includes Any potential header files, or include statements that need to be added to the codegeneration because of the usage of the defined DoIt

#Types Types are the game-supported Types (simple and complex).

<!ELEMENT type (displayName, format?, codeSymbol, reg?, slotRefs?, gui?)>
<!ATTLIST type
   keyword   ID      #REQUIRED
>

###Attributes
Keyword A unique ID used internally by ScriptEase and XML to reference this Type

###Content
displayName Required. What will be displayed to the user when selecting the appropriate Type.
format Provides a place to specify any special resolution methods to the value of this given Type. For example, the Translator author can specify that Objects of String Type have a value that is encompassed by double quotation marks.
codeSymbol Should match the Type's name as seen in the game code. (Examples: int, trigger, float)
reg Provides optional validation to verify if the Type's value matches this regular expression.
slotRefs List of slots that define which Slots are associated with this Type. (Example: NWN's "creature" Type has the Slots "ScriptHeartbeat", "ScriptOnNotice", etc..)
gui GUI provides an optional place to specify the GUI object associated with setting the value of this Type. Possibilities are currently : "JTextField", "JComboBox", and "JSpinner".

#Slots A slot is our name for a specific game event hook. They are used in code generation and File I/O systems to know when that script will be fired and where that script file goes.

The slots list has a defaultFormat attribute that must reference a format in the Language Dictionary. defaultFormat is the format that should be used to start code generation for any slot that does not specify a different starting format. It's used to distinguish between different styles of file, like NWN's difference between the usual int main(){} file and the conversation conditional scripts that do not have a main, but an int StartingConditional() { instead.

<!ELEMENT slot (displayName, implicits?, parameters?)>
<!ATTLIST slot
   keyword   ID         #REQUIRED
>

###Attributes
Keyword Unique ID used internally by ScriptEase and XML to reference this Slot

###Content
displayName The display name is required and is what may be displayed to the user when selecting the appropriate Slot.
implicits List of KnowIts that can be inferred from the Slot. (Example: NWN's OnBlocked Slot allows us to get the Blocker with an implicit GetBlocker() call, and so we reference the appropriate DoIt here.
parameters List of implicit KnowIts that should be added to function generation for that Slot. (Example: Pinball's kSwitchRising needs the switchId, desc, and theEvent parameters in every function generated).

#Maps Maps are provided to allow for arbitrary mapping of data that may not have been covered by the API. This greatly increases the flexibility of API Dictionary, as the Translator author may use them to cover areas undeveloped in the current code generation.

<!ELEMENT maps (map)+>
<!ELEMENT map (entry)+>
<!ATTLIST map
   id   ID   #REQUIRED
   default   CDATA   #REQUIRED
>

###Attributes
ID Unique ID used internally by ScriptEase and XML to reference this map
Default Default value you want non-entries to take since they are not specified

###Content
Entry Key-value pair of an entry in the map. Entry is an XML element with a 'key' attribute to store the key, and the element's text content is the value.
⚠️ **GitHub.com Fallback** ⚠️