Global Python Scripts

Revision as of 07:45, 7 September 2011 by Dʹlanor (Talk | contribs) (→‎xAgeSDLIntShowHide)

Cyan has made global Python scripts which can be used in combination with SDL states. The big advantage of using global scripts is that you do not have to write your own Python scripts.

These scripts require parameters which must be passed to them from the prp file. If you are using 3DS Max you can see these parameters in the roll-out of your Python file component (provided that you have extracted, decompiled and installed the Python files in the Python folder within your Max export folder). Blender users do not have this benefit.

In any case you will need to know what those parameters actually do before you can make use of global Python scripts. That is what this tutorial intends to explain.

This tutorial discusses the global Python scripts as found in Uru:CC (and Drizzle/Offline KI modifications if available). MOULa Python scripts may have additional parameters.


A work in progress. More to come...

Python parameters and ID numbers

The parameters we can pass to Python scripts are the variables starting with "ptAttrib". That is all you need to know about Python for this tutorial. This part of the Python script is shown at the beginning of each section (mainly for the benefit of Blender/PyPRP 1.6 users).

Each parameter has a unique ID number. It is important that this number matches the one sent by the prp file. The Max plugin takes care of that automatically. PyPRP 1.6 however assigns ID numbers in the order of appearance in the AlcScript. This would be fine if global Python scripts used consistent ID numbering, but unfortunately that is not the case. For example, take a look at the first script xAgeSDLBoolSet and you'll see that it goes from ID 2 straight towards ID 7. In AlcScript we work around that by adding fake parameters of the type "skip".

xAgeSDLBoolSet

actTrigger = ptAttribActivator(1, 'Activator')
stringVarName = ptAttribString(2, 'Age SDL Var Name')
intValue = ptAttribInt(7, 'Set Var to:', rang=(0, 1))
stringInfo = ptAttribString(8, 'Extra info to pass along')

Sets an SDL variable to 0 (false) or 1 (true). Often used in combination with xAgeSDLBoolRespond.

In most cases you'll probably want to use xAgeSDLBoolToggle instead. xAgeSDLBoolSet is useful for those events which you want to be irreversible, or which are controlled by different activators (for example a device with separate on and off buttons).

  1. Activator to trigger this Python file. Important: Do not make the activator trigger the responder directly. You have to let Python take care of that.
  2. SDL variable to set. Must be a variable of TYPE BOOL.
  3. skipped
  4. skipped
  5. skipped
  6. skipped
  7. Value to set. Must be 0 or 1.
  8. Forget about this for now and just leave it blank. This info string is not used in combination with other global Python scripts.

AlcScript

<object name>:
    logic:
        actions:
          - type: pythonfile
            tag: BoolSet
            pythonfile:
                file: xAgeSDLBoolSet
                parameters:
                  - type: activator
                    ref: logicmod:<logic modifier name>
                  - type: string
                    value: <name of BOOL SDL to set>
                  - type: skip
                  - type: skip
                  - type: skip
                  - type: skip
                  - type: int
                    value: <0 or 1>
                  - type: string
                    value: <info string>

Notes:
1) If you are implementing the "separate on / off buttons" scenario make sure one activator sets value 0 and the other activator sets value 1.
2) The final parameter is not needed when its string value remains blank.

xAgeSDLBoolToggle

actTrigger = ptAttribActivator(1, 'Activator')
stringVarName = ptAttribString(2, 'Age SDL Var Name')
stringInfo = ptAttribString(5, 'Extra info to pass along')

Toggles an SDL variable between 0 (false) and 1 (true). Often used in combination with xAgeSDLBoolRespond.

  1. Activator to trigger this Python file. Important: Do not make the activator trigger the responder directly. You have to let Python take care of that.
  2. SDL variable to toggle. Must be a variable of TYPE BOOL.
  3. skipped
  4. skipped
  5. Forget about this for now and just leave it blank. This info string is not used in combination with other global Python scripts.

AlcScript

<object name>:
    logic:
        actions:
          - type: pythonfile
            tag: BoolToggle
            pythonfile:
                file: xAgeSDLBoolToggle
                parameters:
                  - type: activator
                    ref: logicmod:<logic modifier name>
                  - type: string
                    value: <name of BOOL SDL to toggle>
                  - type: skip
                  - type: skip
                  - type: string
                    value: <info string>

Note: The parameters 3 (skip), 4 (skip) and 5 (string) are not needed when the final string value remains blank. This example shows how to skip parameters in order to match the Python file, which jumps from id 2 to id 5.

xAgeSDLBoolRespond

stringVarName = ptAttribString(1, 'Age SDL Var Name')
respBoolTrue = ptAttribResponder(2, 'Run if bool true:')
respBoolFalse = ptAttribResponder(3, 'Run if bool false:')
boolVltMgrFastForward = ptAttribBoolean(4, 'F-Forward on VM notify', 1)
boolFFOnInit = ptAttribBoolean(5, 'F-Forward on Init', 1)

Runs either responder 2 or responder 3 in response to an SDL state change. The actual state change is handled by another Python script, usually xAgeSDLBoolSet or xAgeSDLBoolToggle.

  1. SDL variable to monitor. Must be a variable of TYPE BOOL.
  2. Responder to run if SDL variable is true (1).
  3. Responder to run if SDL variable is false (0).
  4. Should the responders run in fast forward mode on VaultManager notify? In FF mode all animations and sounds are skipped unless they are looped. In short: This mode skips to whatever situation you would have after all the events within the responder have finished. VM notify happens when a server admin changes an SDL state through the VaultManager (or another administration tool). For maximum effect you'll want to set this to false.
  5. Should the responders run in fast forward mode On Init? On Init is when the age loads. Use the "false" setting with caution. It makes the responders run each time a player links in and in a multiplayer environment you probably don't want your doors (or whatever) slamming each time that happens. So to be on the safe side set FF to true here.

AlcScript

<object name>:
    logic:
        actions:
          - type: pythonfile
            tag: BoolRespond
            pythonfile:
                file: xAgeSDLBoolRespond
                parameters:
                  - type: string
                    value: <name of BOOL SDL to monitor>
                  - type: responder
                    ref: :<responder to run if bool true>
                  - type: responder
                    ref: :<responder to run if bool false>
                    #F-Forward on VM notify
                  - type: bool
                    value: false
                    #F-Forward on Init
                  - type: bool
                    value: true

xAgeSDLBoolShowHide

stringVarName = ptAttribString(1, 'Age SDL Var Name')
boolShowOnTrue = ptAttribBoolean(2, 'Show on true', 1)

Shows or hides an object based on the value of a boolean SDL variable. Additionally toggles the physics of the object (which makes it useful for enabling/disabling regions as well).

xAgeSDLBoolShowHide can be used in combination with xAgeSDLBoolToggle to trigger the change. There is no smooth transition between the visible and invisible states. If you prefer animated transitions xAgeSDLBoolRespond is a better choice since it supports responders.

  1. SDL variable to monitor. Must be a variable of TYPE BOOL. For the name of the variable Cyan often uses the suffix "Vis" as in "nb01ConesVis".
  2. Should the object be shown on true (1) or on false (0)? For your own (and other people's) sanity you should match this to the name of your SDL variable. If for example the SDL variable is called "MySecretObjectVisible" set this to true, and if it is called "MySecretObjectHidden" set it to false.

AlcScript

<object name>:
    logic:
        actions:
          - type: pythonfile
            tag: BoolShowHide
            pythonfile:
                file: xAgeSDLBoolShowHide
                parameters:
                  - type: string
                    value: <name of BOOL SDL to monitor>
                  - type: bool
                    value: true

In this example the object will be shown when the SDL value is set to true(1) and hidden when it is set to false(0). To configure this the other way around just change the second parameter's value to false.

xAgeSDLIntActEnabler

stringSDLVarName = ptAttribString(1, 'Age SDL Variable')
actActivator = ptAttribActivator(2, 'Activator')
stringStartValues = ptAttribString(3, 'Active state values')

Disables or enables an activator based on the value of an SDL variable. This can be used to prevent interaction with clickable objects.

  1. SDL variable to monitor. It can be a variable of type BOOL, BYTE or INT. For the name of the variable Cyan often uses the suffix "Func" as in "nb01GardenLightsFunc". If you are preventing interaction with a clickable until another puzzle is solved you can tie xAgeSDLIntActEnabler to the same SDL variable as your puzzle and kill two birds with one stone.
  2. The activator (logic modifier) you want to disable/enable.
  3. The state(s) in which the activator is enabled. This can be a single number or a comma separated list of numbers.

AlcScript

<object name>:
    logic:
        actions:
          - type: pythonfile
            tag: IntActEnabler
            pythonfile:
                file: xAgeSDLIntActEnabler
                parameters:
                  - type: string
                    value: <name of SDL to monitor>
                  - type: activator
                    ref: logicmod:<logic modifier name>
                  - type: string
                    value: 1

The example shows the most common use: the activator is enabled when the SDL variable is set to 1.

xAgeSDLIntChange

actTrigger = ptAttribActivator(1, 'Activator')
stringVarName = ptAttribString(2, 'Age SDL Var Name')
boolInc = ptAttribBoolean(3, 'Counter: Increment')
boolDec = ptAttribBoolean(4, 'Counter: Decrement')
intMin = ptAttribInt(5, 'Counter: Min', default=0)
intMax = ptAttribInt(6, 'Counter: Max', default=10)
boolLoop = ptAttribBoolean(7, 'Counter: Loop')
stringInfo = ptAttribString(8, 'Optional Hint String')
intSetTo = ptAttribInt(9, "Don't Count, Set To:", default=0)

Sets an SDL variable to a given number. It has an optional counter to increment or decrement the SDL value each time a player triggers the activator. Often used in combination with xAgeSDLIntShowHide or xAgeSDLIntStartStopResp.

  1. Activator to trigger this Python file. Important: Do not make the activator trigger the responder directly. You have to let Python take care of that.
  2. SDL variable to set. Must be a variable of type INT or BYTE.
  3. Set this to true for a counter which increments. Parameter 4 should be false!
  4. Set this to true for a counter which decrements. Parameter 3 should be false!
  5. The minimum value for the counter.
  6. The maximum value for the counter.
  7. Set this to true to make the counter loop through the range defined by parameters 5 and 6.
  8. Forget about this for now and just leave it blank. This info string is not used in combination with other global Python scripts.
  9. If you don't want to use a counter you can directly set a hard value here. Both parameters 3 and 4 should be false in this case!

AlcScript

<object name>:
    logic:
        actions:
          - type: pythonfile
            tag: IntChange
            pythonfile:
                file: xAgeSDLIntChange
                parameters:
                  - type: activator
                    ref: logicmod:<logic modifier name>
                  - type: string
                    value: <name of INT or BYTE SDL to set>
                  - type: bool
                    value: true
                  - type: bool
                    value: false
                  - type: int
                    value: 0
                  - type: int
                    value: 3
                  - type: bool
                    value: true
                  - type: skip
                  - type: int
                    value: 0

This example makes the SDL variable loop through the values 0, 1, 2 and 3.

xAgeSDLIntShowHide

stringVarName = ptAttribString(1, 'Age SDL Var Name')
stringShowStates = ptAttribString(2, 'States in which shown')

Shows or hides an object based on the value of an SDL variable. Additionally toggles the physics of the object (which makes it useful for enabling/disabling regions as well).

xAgeSDLIntShowHide can be used in combination with xAgeSDLIntChange to trigger it. There is no smooth transition between the visible and invisible states.

  1. SDL variable to monitor. Must be a variable of type INT or BYTE.
  2. States in which the object is shown. This can be a single number or a comma separated list of numbers.

AlcScript

<object name>:
    logic:
        actions:
          - type: pythonfile
            tag: IntShowHide
            pythonfile:
                file: xAgeSDLIntShowHide
                parameters:
                  - type: string
                    value: <name of INT or BYTE SDL to monitor>
                  - type: string
                    value: 2

In this example the object will be shown when the SDL value is set to 2. It remains hidden at any other value.

xAgeSDLIntStartStopResp

stringSDLVarName = ptAttribString(1, 'Age SDL Variable')
respStart = ptAttribResponder(2, 'Start Responder')
stringStartValues = ptAttribString(3, 'Start state values')
boolStartFF = ptAttribBoolean(4, 'Fast forward on start', 0)
respStop = ptAttribResponder(5, 'Stop Responder')
boolStopFF = ptAttribBoolean(6, 'Fast forward on stop', 1)

xAgeSDLVarSet

stringSDLVarName = ptAttribString(1, 'Age SDL Variable')
stringSDLVarToSet = ptAttribString(2, 'SDL Variable To Set')
stringStartStates = ptAttribString(3, 'State value tuples')
stringTag = ptAttribString(4, 'Extra info to pass along')

xAgeSDLBoolAndRespond

stringVar1Name = ptAttribString(1, 'Age SDL Var #1')
stringVar2Name = ptAttribString(2, 'Age SDL Var #2')
respBoolTrue = ptAttribResponder(3, 'Run if bool true:')
respBoolFalse = ptAttribResponder(4, 'Run if bool false:')
boolVltMgrFastForward = ptAttribBoolean(5, 'F-Forward on VM notify', 1)
boolFFOnInit = ptAttribBoolean(6, 'F-Forward on Init', 1)

xAgeSDLBoolAndSet

stringOpA = ptAttribString(1, 'AgeSDL Operand 1')
stringOpB = ptAttribString(2, 'AgeSDL Operand 2')
stringResult = ptAttribString(3, 'AgeSDL Result')

xAgeSDLBoolToggleDependent

actTrigger = ptAttribActivator(1, 'Activator')
stringVarEnabler = ptAttribString(2, 'AgeSDL Enabler')
stringVarTarget = ptAttribString(3, 'AgeSDL Var To Change')
stringInfo = ptAttribString(4, 'Extra info to pass along')

xAgeSDLIntRespList

stringSDLVarName = ptAttribString(1, 'Age SDL Variable')
respList = ptAttribResponderList(2, 'ResponderList', byObject=1)
stringFormat = ptAttribString(3, 'Responder name format string')
intMaxState = ptAttribInt(4, 'Max state value', 2)
boolStartFF = ptAttribBoolean(5, 'F-Forward on start', 0)
boolVltMgrFF = ptAttribBoolean(6, 'F-Forward on VM notify', 1)