Custon 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 reminded, 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 that the player has, and how much of the quest is completed. If 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 means if that the player has those parameters, the conversation line will NOT appear. 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 ).

Script Interface

The Script Interface is Storyteller's list of functions for scripting. It is an ongoing process, as the list of functions can grow to provide a polished experience. The list can be found within the Storyteller's directory.

Name Parameters Definition Type
OpenJournalEntry entryTag Opens the Journal entry(Quest) with the given tag Action
SetJournalEntryValue entryTag, value set the Journal Entry(Quest) with the given tag and changes its currentline according to the entry value Action
OpenConversation convoTag opens the conversation with the convoTag Action
CloseConversation closes the current opened Conversation Action
hideUI Stop the UI from displaying in the game window Action
showUI Display the UI in the game window Action
DestroyGameObject gameObjString Destroy the given game object Action
AddItem itemTag, count add count to the quanity of the inventory item with the given tag Action
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
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
ChangeScene sceneName changes the the environment to the given scene Action
ChangeSceneTo sceneName, startObjectName changes the the environment to the given scene and positions the main char Action
playSound soundName play the given sound Action
PrintToConsole message print the given message to the console 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
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
triggerCondition gameObjString trigger the onCondition event on the provided game object Condition