Custom Scripts

From ETC Public Wiki
Jump to: navigation, search

Users can make their own scripts using Pandamonium’s Script Interface. The Script Interface is a ever-expanding library of functions that users can use and add to their scripts. For example, users can make a script that opens a conversation and gives an entry when triggered, rather than using two individual scripts. It's recommended to have some basic knowledge of programming to fully take advantage of custom scripting.


Script Structure (Action)

The anatomy of a script is structured just for the Storyteller, as it's fairly simple. It uses functions from Storyteller's own Script Interface. There is a limitations that affects both types. A script can only hold up to four parameters. Any extra parameters will not show up in the Storyteller.

As a reminder of the types of scripts, action scripts execute functions and parameters. The following structure is what a typical action would like:

   def main(entryTag):
       Interface.OpenJournalEntry(entryTag)


This is a SetJournalEntry script. When initialized, it will add an entry, which is a Quest, to the player's journal. The function is straight from the Storyteller's Script Interface. For it to be recognized, there should be "Interface." prefix before the function. The number of parameters varies for each function. Here is what a script with multiple parameters:

   def main(entryTag, value):
       Interface.SetJournalEntryValue(entryTag, value)


The parameter names within the main parentheses "(name)" are the variable names that appear next to the text boxes in script area of the Object Panel. For the above case, "entryTag" will appear next to the first text box, and "value" will appear next the second text box. If a function with one parameter were to be added to the same script, the parameter would be then added to the end for ordering. The following shows the example:

   def main(entryTag, value, message):
       Interface.SetJournalEntryValue(entryTag, value)
       Interface.PrintToConsole(message)


The PrintToConsole function is added and the parameter (message) is needed. So to display that info, message is added to parameters in the main parentheses. As a reminder, there can only be up to four parameters within the main parentheses.

Script Structure (Condition)

As for condition script, it utilizes IFs, RETURNs, and ELSEs. They can be used in conversations but not in object events. Here is an example of what one would look like:

   def main(entryTag, value):
       if(Interface.HasJournalEntryAndValue(entryTag, value)):
           return True
       else:
           return False

Using these statements can manipulate a script to only do certain things if the condition is met, or not met. For example, the script above checks for which quest the player has, and how much of the quest is completed. When used used in a conversation, if this condition returns True then the line in the conversation where the script was assigned to will be displayed. Whereas in the next example:

   def main(entryTag, value):
       if(Interface.HasJournalEntryAndValue(entryTag, value)):
           return False
       else:
           return True

This script displays the line in the conversation only if the players does not have the journal entry given. By approaching conditions from both sides, the user has more control to hone into the progress of the player in-game.

Using a Condition Script to Trigger an Action

Condition Scripts cannot be used in an objects events. There is no interface in the object scripting area of the Object Panel to evaluate a return value from a Condition Script and then commit some action based on that value. This is where you would have to write a custom script to handle some of these situations.

Some of the simpler needs can be handled using the onCondition event. Here a custom condition script is writen to trigger the onCondition event on a game object. That game object then assigns an action script to that event. To do this follow these steps:

1. Write a condition script. The script must have at least one parameter - the game object to call the onCollision event on. It should look something like this:
def main(gameObjName):
# check if the condition is met
if ( _CONDITION_ ):
# trigger the onCondition event on the given object
Interface.triggerCondition(gameObjName)
2. Assign this script to an onCollision or onClick event (any event other then the onCollision event) on a game object.
3. On the game object that was supplied to the condition script, add an onCondition event and assign to it the action that you want to take place when the condition is met ( the condition returns True ).


Naming Conventions for Custom Scripts

The scripts that are in the default library use a nameing convention to help organize them. This nameing convention should be used for all custom scripts that are created. There are many scripts and the number keeps growing so organization makes finding the script that is needed easier.

The convention follows the following format:

2 char type code "_" ""(Action) or "Has"(Condition) Name(using camel casing)
Example Action script = MC_FillHp
Example Condition script = JE_HasEntry

NOTE: The word "Test" in the name means that the script tests someting and then calls an action NOTE: The word "Trigger" in the the name means that the script tests something and calls an onCondition and/or onCondition2 event.

Here are the 2 char type codes:

2 char type codes

CT Controls
UI User Interface
CC Cameras and Cut Scenes
JE Journal Entry
CO Conversations
MC Main Character
GO Game Object Manipulation
IN Inventory
GD Game Data
CS Change Scene
UD Utility and Debugging


List of Custom Scripts

Here lies the list of all the current custom scripts that are available for use in the Storyteller.


Name Parameters Definition Type
CC_LoopObjectOnRope gameObj, rope, sequenceTime Loop an object along a rope over the given amount of time Action
CC_LoopObjectOnRopeFollow gameObj, rope, sequenceTime Loop an object along a rope, change orientation on curves Action
CC_LoopObjectOnRopeLookAt gameObj, rope, sequenceTime, lookAtObj Loop an object along a rope, orientate to look at the given object Action
CC_RunCamera cameraName UNKNOWN AT THIS TIME Action
CC_RunObjectOnRope gameObj, rope, sequenceTime Move an object along a rope over the given amount of time Action
CC_RunObjectOnRopeFollow gameObj, rope, sequenceTime Move an object along a rope, change orientation on curves Action
CC_RunObjectOnRopeLookAt gameObj, rope, sequenceTime, lookAtObj Move an object along a rope, orientate to look at the given object Action
CO_OpenConversation convo Open the given conversation Action
CO_CloseConversation convo Close the given conversation Action
CS_ChangeScene sceneName Change to the given scene, char stays in the same location Action
CS_ChangeScenePos sceneName, objectName Change to the given scene, move the char to the give object Action
GD_Decrement dataTag Given the tag of the data item, decrease the int value by 1 Action
GD_HasData dataTag, count Given the tag of the data item, return True if the int value = count Condition
GD_HasLess dataTag, count Given the tag of the data item, return True if the int value < count Condition
GD_HasMore dataTag, count Given the tag of the data item, return True if the int value >= count Condition
GD_Increment dataTag Given the tag of the data item, increase the int value by 1 Action
GD_SetData dataTag, count Given the tag of the data item, set the int value to count Action
GO_AddHP gameObjName, hp For the given game object, add hp to its hit point value Action
GO_Destroy gameObjName Remove the given game object from the scene Action
GO_FillHP gameObjName, hp For the given game object, set its hit point value to its max value Action
GO_Kill gameObjName Remove all hit points from the given game object Action
GO_PlayAni gameObjName, aniName, loop For the given game object, play or loop the given animation Action
GO_StopAni gameObjName, aniName For the given game object, stop the given animation Action
GO_SubtractHP gameObjName, hp For the given game object, subtract hp from its hit point value Action
GO_MakeInvincible gameObjName, time For the given game object, set the Invincible flag and start a timer to turn it off Action
IN_AddItem itemTag, count For the given inventory item, add count to its value Action
IN_HasItem itemTag For the given inventory item, return True if its value is at least 1 Condition
IN_HasLessItems itemTag, count For the given inventory item, return True if its value < count Condition
IN_HasManyItems itemTag, count For the given inventory item, return True if its value = count Condition
IN_HasMoreItems itemTag, count For the given inventory item, return True if its value >= count Condition
IN_HasNotManyItems itemTag, count For the given inventory item, return True if its value != count Condition
IN_SubItem itemTag, count For the given inventory item, subtract count from its value Action
IN_ChangeButton itemTag, index Display the given inventory item in the UI in either the first available button or the indexed button Action
JE_EntryChoiceTrigger entryTag1, gameObjName1, entryTag2, gameObjName2, If journal entry1 is open then trigger the onCondition event on game object1, else if journal entry2 is open then trigger the onCondiditon2 event on game object2 Action
JE_HasAtLeastEntryAndValue entryTag, value Return True if the given journal entry is open and its value is >= to the given value Condition
JE_HasEntry entryTag Return True if the given journal entry is open Condition
JE_HasEntryAndValue entryTag, value Return True if the given journal entry is open and its value is = to the given value Condition
JE_HasNotEntry entryTag Return True if the given journal entry is NOT open Condition
JE_HasNotEntryAndValue entryTag, value Return True if the given journal entry IS open and its value is != to the given value Condition
JE_OpenEntry entryTag Open the given journal entry Action
JE_SetEntryValue entryTag, value If the given journal entry is open then set its value to the value given Action
JE_AddEntryValue entryTag, value If the given journal entry is open then add to its value the value given Action
JE_TestItemAdv itemTag, itemValue, entryTag, advValue If the given journal entry is open and the given item value = itemValue then set the journal entry's value to advValue Action
JE_TestValueAdv entryTag, testValue, advValue If the given journal entry is open and its value = testValue then set the journal entry's value to advValue Action
JE_TestValueTrigger entryTag, value, gameObjName If journal entry is open and its value = the given value then trigger the onCondition event on the given game object Action
MC_AddHP hp Add hp to the main characters hit point value Action
MC_FillHP Set the main characters hit point value to its max value Action
MC_Kill gameObjName Remove all hit points from the main character Action
MC_Respawn gameObjString Move the main character to the given game object, reset HP Action
MC_SubtractHP hp Subtract hp from the main characters hit point value Action
UD_PlaySound soundName Play the given sound Action
UD_PrintToConsole message Print the given string to the console for debugging Action
UD_TimerTrigger gameObjName, time Trigger the onTimer event on the provided game obj in time seconds Action
UI_Hide Do not display the User Interface Action
UI_Show Display the User Interface Action

Script Interface

The Script Interface is Storyteller's list of functions for scripting. It is an ongoing process, the list of functions grows to provide a more polished experience. The list can be found in ScriptInterface.py within the Storyteller's directory however, only a Storyteller Maintainer should update this file.

Soryteller users can use these scripts by calling them from custom scripts that they write. Following is the list of functions broken up into catagories.


Controls and UI

Name Parameters Definition Type
hideUI Stop the UI from displaying in the game window Action
showUI Display the UI in the game window Action


Cameras and Cutscenes

Name Parameters Definition Type
RunCamera cameraName switch to the given camera Action
RunObjectOnRope gameObjString,ropeString,sequenceTime,isLoop,followPath,lookAtObject move the given object along a path of waypoints Action


Journal and Quests

Name Parameters Definition Type
OpenJournalEntry entryTag Opens the Journal entry(Quest) with the given tag Action
SetJournalEntryValue entryTag, value set the Journal Entry(Quest) value with the given tag and change its currentline according to the entry value Action
AddToJournalEntryValue entryTag, value add to the Journal Entry(Quest) value with the given tag and change its currentline according to the entry value Action
HasJournalEntry entryTag is the given journal entry tag open Condition
HasJournalEntryAndValue entryTag, valueString is the given journal entry tag open and is it at the given value Condition
HasAtLeastJournalEntryAndValue entryTag, valueString is the given journal entry tag open and is it at the given value or past it Condition


Conversations

Name Parameters Definition Type
OpenConversation convoTag opens the conversation with the convoTag Action
CloseConversation closes the current opened Conversation Action


Main Character Manipulation

Name Parameters Definition Type
AddMainCharHP hpString add Health points to the main character Action
FillMainCharHP fills the main character's Health points to max Action
SubtractMainCharHP hpString subtracts health points from the main Char Action
KillMainChar kills the main char Action
RespawnMainChar gameObjString position the main char at the provided object and max the char's health Action


GameObject Property Manipulation

Name Parameters Definition Type
DestroyGameObject gameObjString Destroy the given game object Action
AddHP gameObjString, hpString adds health points to the gameObj Action
FillHP gameObjString fills the game Object's Health points to max Action
SubtractHP gameObjString, hpString subtracts health points from the game Obj Action
Kill gameObjString kills the game object Action
PlayAnimation gameObjString, animationString, loopString plays (or loops) the provided animation on the provided game object Action
StopAnimation gameObjString, animationString stop the provided animation on the provided game object Action
HideObject gameObjString hide the provided game object - collisions can still occur Action
ShowObject gameObjString show the provided game object Action
MakeInvincible gameObjString, time for the game object set the Invincible property to the time. It will start to count down immediately. Action


Inventory and Game Data

Name Parameters Definition Type
AddItem itemTag, count add count to the quanity of the inventory item with the given tag Action
SubItem itemTag, count subtract count from the quanity of the inventory item with the given tag Action
HasItem itemTag is there at least one of this item Condition
HasManyItems itemTag, count is there exactly this many items Condition
HasMoreItems itemTag, count is there this many or more items Condition
HasLessItems itemTag, count is there fewer than these items Condition
ChangeUIButton itemTag, index display the given item in the UI in either the index provided or the first available button Action
SetGameData dataTag, count setup the given tag in the game data dict with the given count Action
IncrementGameData dataTag given the game data tag, increase the value by 1 if the tag exists Action
DecrementGameData dataTag given the game data tag, decrease the value by 1 if the tag exists Action
HasGameData dataTag, valueString return if the given game data tag has the given value Condition
HasMoreGameData dataTag, valueString return if the given game data tag has at least the given value Condition
HasLessGameData dataTag, valueString return if the given game data tag has fewer than the given value Condition


Changing Scenes

Name Parameters Definition Type
ChangeScene sceneName changes the environment to the given scene Action
ChangeSceneTo sceneName, startObjectName changes the environment to the given scene and positions the main char Action


Utility and Debugging

Name Parameters Definition Type
playSound soundName play the given sound Action
PrintToConsole message print the given message to the console Action
AssignHotKeyEvent key, gameObjectString, event assign the keyboard key to call the provided event on the provided game object Action
triggerCondition gameObjString trigger the onCondition event on the provided game object Action
triggerCondition2 gameObjString trigger the onCondition2 event on the provided game object Action
triggerTimer gameObjString, timeString wait for time (in seconds) and then trigger the onTimer event on the provided game object Action