diff --git a/Scripting.md b/Scripting.md index f1eea1a..464b1a4 100644 --- a/Scripting.md +++ b/Scripting.md @@ -1,5 +1,5 @@ This section will describe how to use the scripting API to add custom macro conditions and actions. -The API is not limited to Python, but the examples showcased here will only be using Python. +The API is not limited to scripts or Python, but the examples showcased here will only be using Python for brevity. # Examples @@ -63,7 +63,7 @@ def script_load(settings): ############################################################################### -# Deregistering is useful if you plan on reloading the script files +# Deregistering is useful if you plan unloading the script files ############################################################################### def script_unload(): advss_deregister_condition(CONDITION_NAME) @@ -94,4 +94,153 @@ The advanced scene switcher offers the following [procedure handlers](https://do * `bool advss_deregister_script_action(in string name)` * `bool advss_deregister_script_condition(in string name)` * `bool advss_get_variable_value(in string name, out string value)` -* `bool advss_set_variable_value(in string name, in string value)` \ No newline at end of file +* `bool advss_set_variable_value(in string name, in string value)` + +## advss_register_script_action + +### name + +The `name` field of calldata object associated with this procedure should specify the id of the action type you want to register. + +### Return value + +The return value can be queried via `success` from the calldata object associated with this procedure. +Returns `true`, if the operation was successful, and `false` otherwise. + +## advss_register_script_condition + +### name + +The `name` field of calldata object associated with this procedure should specify the id of the condition type you want to register. + +### Return value + +The return value can be queried via `success` from the calldata object associated with this procedure. +Returns `true`, if the operation was successful, and `false` otherwise. + +## advss_deregister_script_action + +### name + +The `name` field of calldata object associated with this procedure should specify the id of the action type you want to deregister. + +### Return value + +The return value can be queried via `success` from the calldata object associated with this procedure. +Returns `true`, if the operation was successful, and `false` otherwise. + +### Example +``` +def advss_deregister_action(name): + proc_handler = obs.obs_get_proc_handler() + data = obs.calldata_create() + + obs.calldata_set_string(data, "name", name) + + obs.proc_handler_call(proc_handler, advss_deregister_script_action, data) + + success = obs.calldata_bool(data, "success") + if success == False: + segment_type = "action" if is_action else "condition" + obs.script_log(obs.LOG_WARNING, f'failed to deregister custom action"{name}"') + + obs.calldata_destroy(data) +``` + +## advss_deregister_script_condition + +### name + +The `name` field of calldata object associated with this procedure should specify the id of the condition type you want to deregister. + +### Return value + +The return value can be queried via `success` from the calldata object associated with this procedure. +Returns `true`, if the operation was successful, and `false` otherwise. + +### Example +``` +def advss_deregister_condition(name): + proc_handler = obs.obs_get_proc_handler() + data = obs.calldata_create() + + obs.calldata_set_string(data, "name", name) + + obs.proc_handler_call(proc_handler, advss_deregister_script_condition, data) + + success = obs.calldata_bool(data, "success") + if success == False: + segment_type = "action" if is_action else "condition" + obs.script_log(obs.LOG_WARNING, f'failed to deregister custom condition "{name}"') + + obs.calldata_destroy(data) +``` + +## advss_get_variable_value + +### name + +The `name` field of calldata object associated with this procedure should specify the id of the name of the [variable](https://github.com/WarmUpTill/SceneSwitcher/wiki/Variables) for which you want to get the current value. + +### value + +The `value` field of calldata object associated with this procedure will contain the value of the specified [variable](https://github.com/WarmUpTill/SceneSwitcher/wiki/Variables), if the operation was successful. + +### Return value + +The return value can be queried via `success` from the calldata object associated with this procedure. +Returns `true`, if the operation was successful, and `false` otherwise. + +### Example +``` +def advss_get_variable_value(name): + proc_handler = obs.obs_get_proc_handler() + data = obs.calldata_create() + + obs.calldata_set_string(data, "name", name) + obs.proc_handler_call(proc_handler, "advss_get_variable_value", data) + + success = obs.calldata_bool(data, "success") + if success == False: + obs.script_log(obs.LOG_WARNING, f'failed to get value for variable "{name}"') + obs.calldata_destroy(data) + return None + + value = obs.calldata_string(data, "value") + + obs.calldata_destroy(data) + return value +``` + +## advss_set_variable_value + +### name + +The `name` field of calldata object associated with this procedure should specify the id of the name of the [variable](https://github.com/WarmUpTill/SceneSwitcher/wiki/Variables) for which you want to change the value. + +### value + +The `value` field of calldata object associated with this procedure should specify the value you want to set for the specified [variable](https://github.com/WarmUpTill/SceneSwitcher/wiki/Variables). + +### Return value + +The return value can be queried via `success` from the calldata object associated with this procedure. +Returns `true`, if the operation was successful, and `false` otherwise. + +### Example +``` +def advss_set_variable_value(name, value): + proc_handler = obs.obs_get_proc_handler() + data = obs.calldata_create() + + obs.calldata_set_string(data, "name", name) + obs.calldata_set_string(data, "value", value) + obs.proc_handler_call(proc_handler, "advss_set_variable_value", data) + + success = obs.calldata_bool(data, "success") + if success == False: + obs.script_log(obs.LOG_WARNING, f'failed to set value for variable "{name}"') + + obs.calldata_destroy(data) + return success +``` \ No newline at end of file