Product:

Version:

Search:

Scripting API Reference | Project

22. Scripting API Reference | Project

Module: Project
Class: Model
- Model.%entity_name%
- Model.document()
Class: Entity
Class: ManagedObject
Extensions: ManagedObject

Module: Project

The studio.project module provides access to objects within the project model.

project.workspace

The root workspace ManagedObject of the project.

project.model

The project Model type representation applicable for this version.

project.build()

Builds all the banks to all the platforms listed in the build tab of the preferences dialog.

project.build(build_options)

Builds the project with options object { banks, platforms }.

Building individual banks also builds and updates your project's master banks and master bank strings files.

For example:

// Single banks
    studio.project.build({ banks: 'Weapons' }); // Build the "Weapons" bank to all platforms
    studio.project.build({ banks: 'Music', platforms: ['Desktop', 'PlayStation 4'] }); // Build the "Music" bank for only the "Desktop" and "PlayStation 4" platforms

// Multiple banks
    studio.project.build({ banks: ['Weapons', 'Characters'], platforms: 'Desktop' }); // Build the "Weapons" and "Characters" banks only for the "Desktop" platform
    studio.project.build({ banks: ['Weapons', 'Music'], platforms: ['Desktop', 'PlayStation 4'] }); // Build the "Weapons" and "Music" banks to the "Desktop" and "PlayStation 4" platforms

// Platforms
    studio.project.build({ platforms: 'Desktop' }); // Builds all banks for the "Desktop" platform
    studio.project.build({ platforms: ['Desktop', 'PlayStation 4'] }); // Builds all banks for the "Desktop" and "PlayStation 4" platforms

project.lookup(idOrPath)

Returns a ManagedObject found by GUID or path. The idOrPath passed may be a GUID or path string. For example:

var item = project.lookup("{3a731ab3-ce6d-453d-862e-32050cecf68a}");
var event = project.lookup("event:/path/to/eventname");
var eventFolder = project.lookup("event:/path/to/foldername");
var snapshot = project.lookup("snapshot:/snapshotname");
var vca = project.lookup("vca:/vcaname");

Paths are formatted using the pattern type:/path/to/item, where type is one of:

event
snapshot
bus
vca
asset
parameter
effect
tag
profilersession

Paths can also be used to find container items, such as finding a folder in the event hierarchy.

project.create(entityName)

Returns a new instances of a ManagedObject of the given entity name. This will create any required child objects for the object (e.g. creating an Event will create and attach its EventMixer).

project.deleteObject(managedObject)

Deletes the managedObject and its references, if any, from the project. This is the equivalent to deleting an item in the user interface.

project.filePath

The absolute path to the project's .fspro file on disk.

project.importAudioFile(filePath)

Imports an audio asset into the project and returns an AudioFile ManagedObject, or null if importing failed. The file is always imported into the root audio bin folder. Use the AudioFile.container relationship to reassign it to another folder.

project.audioFileImported.connect(callback)

Sets a function to be called when an audio file is imported, with the signature function(audioFile).

project.audioFileImported.disconnect(connectFunction)

Disconnects the connectFunction once it is no longer needed. It is important to disconnect the connected signals when they are no longer needed, otherwise they can accumulate and cause unexpected behaviour.

project.buildStarted.connect(callback)

Sets a function to be called before banks are built, with the signature function(). For example:

studio.project.buildStarted.connect(function() {
    alert("Build about to start");
});

project.buildStarted.disconnect(connectFunction)

function connectToBuildStart() {
    alert("Build about to start");
};

studio.project.buildStarted.connect(connectToBuildStart);

studio.project.buildStarted.disconnect(connectToBuildStart);

project.buildEnded.connect(callback)

Sets a function to be called after banks are built, with the signature function(success). The success argument will be false if a build error occurs or the build is cancelled by the user, and true otherwise. For example:

studio.project.buildEnded.connect(function(success) {
    alert(success ? "Build has ended well" : "Build has ended badly");
});

project.buildEnded.disconnect(connectFunction)

function connectToBuildEnd() {
    alert("Build about to end");
}

studio.project.buildEnded.connect(connectToBuildEnd);

studio.project.buildEnded.disconnect(connectToBuildEnd);

project.distanceRolloffType

An enum corresponding to different distance attenuation roll-off types available to spatial effects. Possible values are:

LinearSquared
Linear
Inverse
InverseTapered
Custom

project.parameterType

An enum corresponding to different game parameter types available. Possible values are:

User
Distance
Direction
Elevation
EventConeAngle
EventOrientation
UserLabeled

project.regionLoopMode

An enum corresponding to different loop modes of a loop region. Possible values are:

None
Looping
Magnet

Class: Model

The studio.project.model provides access to information about the available model types. Data within the model is represented as a collection of Entity types upon which ManagedObjects are based. You can look entities up by name. For example:

studio.project.model.Event.findInstances(); // find all Event instances

Model.%entity_name%

Returns the studio.project.Entity associated with the entity_name.

Model.document()

Returns a string describing every studio.project.Entity.

Class: Entity

A studio.project.Entity provides information about the type of a ManagedObject.

The entity for a given ManagedObject can be retrieved using ManagedObject.entity. This provides the string representation for an entity, which can then be looked up in the studio.project.model.

Entity.superEntities

An array of strings representing the entity types inherited by this entity.

Entity.isAbstract

Boolean set to true if an entity can be instantiated, or is a base class for other entity types.

Entity.isGlobal

Boolean set to true if an entity exists globally, rather than on a per project basis.

Entity.isSingleton

Boolean set to true if only a single ManagedObject instance of the entity can exist at any given time.

Entity.properties

Returns an object containing named properties that represent each ManagedObject property available for this entity. The value is a description object containing:

dataType [string]
defaultValue [variant]

Entity.relationships

Returns an object containing named relationship that represent each ManagedObject relationship available for this entity. The value is a description object containing:

cardinality [string]
destinationType [string]
isRequired [bool]

Entity.findInstances([options])

Returns an array of ManagedObject instances of a given entity type.

You can optionally pass an options object { searchContext, includeDerivedTypes }. Passing a managed object for the searchContext field will bound the object search to a particular file. Passing true for the includeDerivedTypes field will allow derived types of the given entity to be returned.

For example:

// find all SingleSounds within the project
studio.project.model.SingleSound.findInstances();

// find all SingleSounds within the currently selected event
studio.project.model.SingleSound.findInstances({ searchContext: studio.window.browserCurrent() });

// find all GroupTracks, ReturnTracks and MasterTracks within the currently selected event
studio.project.model.AudioTrack.findInstances({ searchContext: studio.window.browserCurrent(), includeDerivedTypes: true });

Entity.singletonInstance()

Returns the singleton ManagedObject instance of a particular entity type. An error will be thrown if the entity is not a singleton type.

Entity.document()

Returns a string describing the entity, including its properties and relationships.

Class: ManagedObject

Project level data in Studio is represented as a graph of ManagedObjects. A ManagedObject is comprised of:

id: Unique identifier (GUID).
entity: A description of the object type (e.g. Event, MixerGroup, Snapshot).
properties: Each property is a simple data field (e.g. float, bool, string) with a value.
relationships: Links to other ManagedObjects, known as destinations. These can be ToOne or ToMany, and may or may not be ordered.

Beyond the generic interface presented for each ManagedObject, a number of extension functions are available for ManagedObjects of a particular studio.project.Entity type.

The root ManagedObject of a project can be retrieved using studio.project.workspace. Objects within a project of a particular studio.project.Entity can be retrieved using Entity.findInstances().

ManagedObject.entity

A string representing the object's studio.project.Entity type (e.g. Event). Lookup studio.project.model to inspect details about the entity. Immutable.

ManagedObject.id

The object's unique ID. Immutable.

ManagedObject.isValid

Returns whether an object is in a valid state. Immutable.

ManagedObject.properties

Extended API. Returns an object of type studio.project.ManagedPropertyMap. Provides access to an object's properties. Immutable.

ManagedObject.relationships

Extended API. Returns an object of type studio.project.ManagedRelationshipMap. Provides access to an object's relationships. Immutable.

ManagedObject.isOfType(entityName)

Returns true if the object has an entity that matches entityName, or is of a derived type.

ManagedObject.isOfExactType(entityName)

Returns true if the object has an entity that exactly matches entityName. This does not include derived types.

ManagedObject.%property_name%

Convenience API. Provides access to a managed object property's value. Setting the property (with the = operator) will set the property value.

ManagedObject.%relationship_name%

Convenience API. Provides access to a managed object relationship's destinations. Getting a ToOne relationship will return the single destination object (or null if it is unassigned). Getting a ToMany relationship returns an array of destinations (or an empty array if it has no destinations). Setting a ToOne relationship (with the = operator) will set replace the current destinations. ToMany relationships cannot be modified with the = operator, and must be edited via the Extended API.

ManagedObject.dump()

Logs all members.

ManagedObject.document()

Returns a string describing this ManagedObject's type studio.project.Entity.

As an example, calling studio.project.workspace.mixer.masterBus.volume = 2, would walk through the Workspace's relationship to the global Mixer, then the Mixer's relationship to the MasterBus, and finally sets the volume property on the MasterBus to 2dB.

Note that the above example uses the Convenience API to walk the graph in a more readable fashion. The equivalent (using the Extended API) would be studio.project.workspace.relationships.mixer.destinations[0].relationships.masterBus.destinations[0].properties.volume.setValue(2). As such, the Convenience API is suitable for quick traversal of the graph, while the Extended API provides access to advanced attributes of properties and relationships.

ManagedPropertyMap.parent

The owning managed object of the property map. Immutable.

ManagedPropertyMap.%property_name%

Returns an object of type studio.project.ManagedProperty for the given property name. Immutable.

ManagedPropertyMap.dump()

Logs all members.

ManagedRelationshipMap.parent

The owning managed object of the relationship map. Immutable.

ManagedRelationshipMap.%relationship_name%

Returns an object of type studio.project.ManagedRelationship for the given relationship name. Immutable.

ManagedRelationshipMap.dump()

Logs all members.

ManagedProperty.parent

The owning managed object of the property. Immutable.

ManagedProperty.name

Name of the property. Immutable.

ManagedProperty.dataType

The type of data stored by this property's value. Immutable.

ManagedProperty.value

The value stored by the property. Immutable.

ManagedProperty.defaultValue

Default value the property takes when created. Immutable.

ManagedProperty.setValue(value)

Sets the value stored by the property.

ManagedProperty.dump()

Logs all members.

ManagedRelationship.parent

The owning managed object of the relationship. Immutable.

ManagedRelationship.name

Name of the relationship. Immutable.

ManagedRelationship.cardinality

A string representing the object's cardinality. Either ToOne or ToMany. Immutable.

ManagedRelationship.ordering

"A string representing the object's ordering. Either None if it is unordered, Ordered if its ordering is saved to the project, or Transient if ordering is per user. Immutable.

ManagedRelationship.destinations

An array of managed object destinations. Immutable.

ManagedRelationship.add(managedObject)

Appends a new destination to a relationship. Replaces the current destination for a ToOne relationship.

ManagedRelationship.insert(index, managedObject)

Inserts a new destination to a relationship at a given index. Index must be in range [0, destinations.length].

ManagedRelationship.remove(managedObject)

Removes a destination from a relationship.

ManagedRelationship.dump()

Logs all members.

Extensions: ManagedObject

Particular types of ManagedObjects contain extended functionality, based on their studio.project.Entity type.

Asset.getAssetPath()

Returns the path of the file the asset refers to, relative to the project assets directory.

Asset.setAssetPath(filePath)

Sets the path of the file the asset refers to, relative to the project assets directory. Calling this function will move the underlying file asset on disk.

Asset.getAbsoluteAssetPath()

Returns the absolute path of the file the asset refers to.

AudioTrack.addAutomationTrack(automatableObject, propertyName)

Creates an automation track for a given property of an automatable object. The automatableObject argument can be any automatable object of the track such as an instrument, a mixer effect or the mixer bus of the track itself. The propertyName argument has to be a valid automatable property of the specified automatable object. For example:

// adds an automation track for a master track's volume
var event = studio.project.workspace.addEvent("New Event", true);
var masterTrack = event.masterTrack;
var automationTrack = masterTrack.addAutomationTrack(masterTrack.mixerGroup, "volume");

// adds an automation track for a gain effect's gain 
var gainEffect = masterTrack.mixerGroup.effectChain.addEffect("GainEffect");
var automationTrack2 = masterTrack.addAutomationTrack(gainEffect, "gain");

AutomatableObject.addAutomator(propertyName)

Creates an automator for a given property of the automatable object. For example:

var automator1 = sound.addAutomator("volume"); // adds an automator for the volume property of the sound
var automator2 = sound.addAutomator(sound.pitch); // alternatively, the property can be used as an argument

AutomatableObject.addModulator(modulatorType, propertyName)

Creates a modulator for a given property of the automatable object. The modulatorType argument determines the entity type of the modulator, and must be RandomizerModulator, ADSRModulator, or SidechainModulator. For example:

var randModulator = sound.addModulator("RandomizerModulator", "volume"); // adds a randomizer modulator for the volume property of the sound
var ahdsrModulator = sound.addModulator("ADSRModulator", sound.pitch); // alternatively, the property can be used as an argument

Automator.addAutomationCurve(parameter)

Creates an automation curve on the parameter specified. The parameter argument can be either a GameParameter or the Timeline of the event containing the object being automated. For example:

// adds an automation curve to a master track's volume, on the timeline
var event = studio.project.workspace.addEvent("New Event", true);
var mixerGroup = event.masterTrack.mixerGroup;
var automator = mixerGroup.addAutomator("volume");
var automationCurve = automator.addAutomationCurve(event.timeline);

// adds an automation curve to a gain effect, on a parameter
var gainEffect = mixerGroup.effectChain.addEffect("GainEffect");
var automator = gainEffect.addAutomator("gain");
var rpmParameter = studio.project.lookup("parameter:/RPM");
var automationCurve = automator.addAutomationCurve(rpmParameter.parameter);

AutomationCurve.addAutomationPoint(position, value)

Creates an automation point on the curve at a given position and value. The position must be within the range of the curve's parameter and the value must be within the value range of the automated property.

Bank.getPath()

Returns the bank's path as a string.

ConvolutionReverbEffect.setIRFromFilePath(filePath)

Sets the impulse response for a convolution reverb effect. The file path must be an absolute path referring to an audio data file.

Event.isPlaying()

Returns true if an event is playing.

Event.isPaused()

Returns true if an event is paused.

Event.isStopping()

Returns true if an event is stopping.

Event.isRecording()

Returns true for profiler sessions with recording enabled.

Event.play()

Plays the event. The equivalent of pressing the play button in the transport controls.

Event.togglePause()

Toggle pause for an event. The equivalent of pressing the pause button in the transport controls.

Event.stopImmediate()

Stops an event immediately, skipping the stopping state.

Event.stopNonImmediate()

Stops an event. The event will enter the stopping state.

Event.returnToStart()

Moves the playback position to the cursor position if called while the event is playing. Moves the cursor position back to the start of the timeline while the event is stopped.

Event.keyOff()

Triggers the keyoff behavior for a sustain point.

Event.toggleRecording()

Toggles the recording state for a profiler session.

Event.getPath()

Returns the event's path as a string.

Event.get3DAttributes()

Returns an object representing the currently auditioned 3D attributes:

radialDistance [number]
azimuth [number]
height [number]
rotation [number]

Event.set3DAttributes(attributes)

Sets the currently auditioned 3D attributes based on an attributes object. The properties of the attributes object match the Event.get3DAttributes() function.

Event.getCursorPosition(parameter)

Returns the cursor position as a number. The parameter argument must be a Timeline or GameParameter.

Event.setCursorPosition(parameter, position)

Sets the cursor position to a number. The parameter argument must be a Timeline or GameParameter.

Event.getPlayheadPosition(parameter)

Returns the playback position of a parameter as a number. The parameter argument must be a Timeline or GameParameter.

Event.getParameterPresets()

Returns an Array of all GameParameter objects referenced by an event. This includes any implicitly referenced parameters. The order of the Array matches the order displayed in the transport bar.

Event.addGameParameter(parameterDefinition)

Adds a game parameter to the event. The parameterDefinition argument can either be a ParameterPreset, a GameParameter, or an Object defining the parameter to create:

name: The name of the parameter as a string.
type: A studio.project.parameterType.
min: The minimum value of the parameter range (number).
max: The maximum value of the parameter range (number).

Event.addGroupTrack(name)

Adds a group track with the given name to the event.

Event.addReturnTrack(name)

Adds a return track with the given name to the event.

Event.addMarkerTrack()

Adds a marker track to the event.

Folder.getItem(path)

Returns the item at the relative path specified. Returns undefined if the item cannot be found. For example:

var event = studio.project.workspace.masterEventFolder.getItem("sfx/explosion_event");

GameParameter.getCursorPosition()

Returns the cursor position of the global game parameter as a number. Returns undefined if the scope of the game parameter is not global. For example:

var globalParameterPreset = studio.project.lookup("parameter:/game_state/time_of_day"); // return a ParameterPreset object
var timeOfDay = globalParameterPreset.parameter.getCursorPosition();

GameParameter.setCursorPosition(position)

Sets the cursor position of the global game parameter to a number. For example:

var globalParameterPreset = studio.project.lookup("parameter:/game_state/time_of_day"); // return a ParameterPreset object
globalParameterPreset.parameter.setCursorPosition(1300);

GroupBus.getItem(path)

Returns the MixerBus at the relative path specified. Returns undefined if the bus cannot be found. For example:

var bus = studio.project.workspace.mixer.masterBus.getItem("sfx/player");

GroupTrack.addSound(parameter, soundType, start, length)

Adds a sound to the track on the parameter specified. The soundType argument determines the entity type of the sound and must be SingleSound, MultiSound, or ProgrammerSound. The start value must be in the range of the parameter.

MarkerTrack.addNamedMarker(name, position)

Adds a named marker to the track at the given position.

MarkerTrack.addRegion(position, length, name, loopMode)

Adds a region to the track at the given position with the given length. The name of the region can be set by passing in a valid name argument. The loop mode of the region defaults to project.regionLoopMode.Looping if loopMode is undefined. The loop mode can be set by passing in a valid loopMode argument, as described by the project.regionLoopMode enum.

MarkerTrack.addTransitionMarker(position, destination)

Adds a transition marker to the track at the given position. The destination of the transition marker can be set by passing in a valid destination argument. The destination argument can either be a NamedMarker or a LoopRegion.

MarkerTrack.addTransitionRegion(position, length, destination)

Adds a transition region to the track at the given position with the given length. The destination of the transition region can be set by passing in a valid destination argument. The destination argument can either be a NamedMarker or a LoopRegion.

MarkerTrack.addSustainPoint(position)

Adds a sustain point to the track at the given position.

MasterAssetFolder.getAsset(path)

Returns the Asset at the relative path specified. Returns undefined if the item cannot be found. For example:

studio.project.workspace.masterAssetFolder.getAsset("music/level_01.wav");

MixerBus.getInputFormat()

Returns the effective input format for a MixerBus object as an enumeration.

MixerBus.getOutputFormat()

Returns the effective output format for a MixerBus object as an enumeration.

MixerBusEffectChain.addEffect(effectDefinition)

Creates an effect and adds it to the end of the chain. The effectDefinition argument can either be an EffectPreset, a MixerEffect that is a preset, or one of the following strings:

ThreeEQEffect
ChannelMixEffect
ChorusEffect
CompressorEffect
ConvolutionReverbEffect
DistortionEffect
DelayEffect
FlangerEffect
GainEffect
LimiterEffect
MultibandEqEffect
PitchShifterEffect
SFXReverbEffect
TransceiverEffect
TremoloEffect
HighpassEffect
HighpassSimpleEffect
LowpassEffect
LowpassSimpleEffect
ParamEqEffect
SpatialiserEffect
ObjectSpatialiserEffect
LoudnessMeter

MixerStrip.getPath()

Returns the bus or VCA's path as a string.

Parameter.getPlayheadPosition()

Returns the playback position of a parameter, within the context of the associated event.

ParameterPreset.getPath()

Returns the parameter's path as a string.

ParameterProxy.getCursorPosition()

Returns the cursor position as a number, within the context of the associated event. The equivalent of calling parameterProxy.event.getCursorPosition(parameterProxy.preset).

ParameterProxy.setCursorPosition(position)

Sets the cursor position to a number, within the context of the associated event. The equivalent of calling parameterProxy.event.setCursorPosition(parameterProxy.preset, position).

Sound.setFadeInCurve(length, curveShape)

Sets the fade-in curve of the sound to the specified length and curveShape. If no fade-in curve exists on the sound, one is created. If length is approaching zero, no curve is added - if the curve has an existing fade-in curve, it is removed. If no curveShape is provided, the default shape is used instead.

Sound.setFadeOutCurve(length, curveShape)

Sets the fade-out curve of the sound to the specified length and curveShape. If no fade-out curve exists on the sound, one is created. If length is approaching zero, no curve is added - if the curve has an existing fade-out curve, it is removed. If no curveShape is provided, the default shape is used instead.

Timeline.getCursorPosition()

Returns the cursor position as a number, within the context of the associated event. The equivalent of calling timeline.event.getCursorPosition(timeline).

Timeline.setCursorPosition(position)

Sets the cursor position to a number, within the context of the associated event. The equivalent of calling timeline.event.setCursorPosition(timeline, position).

Triggerable.addParameterCondition(parameter, min, max)

Adds a parameter condition for a given parameter to a triggerable object. The parameter argument can either be a ParameterPreset or a GameParameter. The range of the parameter condition is specified using the min and max. If max is undefined, the maximum of the parameter condition will be set to min. For a labeled parameter, the max argument will be ignored. For example:

var continuousCondition = loopRegion.addParameterCondition(studio.project.lookup("parameter:/Distance Parameter"), 0, 1000);
var labeledCondition = singleSound.addParameterCondition(studio.project.lookup("parameter:/Current Country"), "Australia");
labeledCondition = transitionMarker.addParameterCondition(studio.project.lookup("parameter:/Current Country"), "Australia");
labeledCondition = transitionRegion.addParameterCondition(studio.project.lookup("parameter:/Current Country"), "Australia");