Custom IDs

Table of Contents

Detailed Workflow Guide

Detailed Formatting Guide

Generator Syntax Table

Operator Syntax Tables

 

Detailed Workflow Guide

Video Games, VR, and other types of interactive media are often created with the use of complex applications, traditionally called "engines," to build and manage projects.

Projects created with these engines are often quite large in size, and are made up of all the digital assets that will be in your finished product. These assets, which include character models, environments, and sound effects, among other asset types, often have very specific naming conventions, which are meaningful to the project.

Gem projects are made up of a number components which contain unique IDs that ensure the contents of your script are appropriately connected within your Gem Studio. These IDs are not editable, but it's important that users also have the ability to transfer this data to their engine of choice, respecting the naming conventions in use for the projects. Enter Custom IDs.

 

Users can create Custom IDs in Games projects, which can be used to keep your project info in sync with your development engine.

Custom IDs can be created from your project's Reports document. To create a Custom ID for a particular script element or catalog item type, select the 'Use Custom IDs' option from the 'Edit' menu to surface the Custom ID editor.

 

Detailed Formatting Guide

You can set unique Custom ID conventions for each type of script element and catalog item in your project that are comprised of the following components:

• Generators: References and evaluates a node, node content, or catalogue item.
• Outputs: The result automatically produced by a generator.
• Operators: Manipulates the output created by a generator.
• Parameters: Provide values for generators or operators. Not all generators accept parameters.

The codes for these components are arranged in the following syntax:

STATIC_${generator(parameter):operator(parameter)}_STATIC

Here, the “STATIC” element refers to fixed text that you have the option of adding to your convention. 

It is not necessary to use all components in a convention. Your conventions can consist of multiple Generator and Operator combinations, separated by use of the ${} wrapping.

For example:
You want to set a convention to create an ID which replaces all spaces in sequence names with underscores. This convention would look like this:

${seqName:replaceSpace(‘_’)}

Using the example above, ‘seqName’ is the Generator and ‘replaceSpace’ is the Operator. These are always separated by a colon.

The value of the Operator is ‘_’. These are always written in parentheses following the Operator. If the value is a string, it must be put in apostrophes. If it is a number, no apostrophe is necessary. 

You can add multiple operators to a Generator which will function in sequence, always referencing the output of the preceding operation. For example, if you wanted the Custom IDs for your sequences to also be in uppercase, it would look like this:
${seqName:replaceSpace(‘_’):upperCase}

Your convention can include more than one Generator. For example, if you wanted to include the date on your Custom ID, you would add a new section to the convention, like this:
${seqName:replaceSpace(‘_’):upperCase}${now:str}

If you enter a convention with invalid syntax, an error message will be displayed, with a list of supported syntax for that option, similar to the following:

To apply a convention, add the desired code to the convention field and click save. You can create multiple conventions at the same time.

To edit a convention, change the code in the corresponding field and click save.

To delete an individual convention, click the X located on the right hand side of the convention field and click save.

To delete all conventions, click the ‘Clear All’ button and confirm.

 

A Note on Counter Generators and their Respective Operators:

For each Custom ID convention field, users may apply optional settings for the Counter generator that correspond to functions for Counter Scoping, and Counter Increments, as well as a Counter-specific padding operator. These functions provide the user with a greater level of control over the Counter output.

• The first component is Counter Scoping, selected from the top dropdown field. Here, you can choose if and when a Counter’s output should be reset, based on the corresponding element's position within the project containers (Episodes, Scenes, Lanes), or within Sequences for the various script elements (Gameplay, Character, Dialogue, and Directive).
  • For example, if you set the Counter for a ‘character’ element Custom ID to be scoped within a Lane, the Counter output will reset every time the Character appears in a new lane. If you set it to Scene, it will reset on each new scene, etc…
  • Please note that Sequence scoping is not available for branch or element types.
• The second component is Counter Increments. In this field, you can define by what increment the Counter output increases. This component is optional, and by default all Counter increments are set to 1.
  • For example, setting the Increment for the Counter output on a ‘Dialogue’ element Custom ID to 10, the ID will increase the number generated for each dialogue instance in Increments of ten (10, 20, 30, 40, 50, etc…).
• The padStart operator can also be applied to a counter generator in order to define the number of digits in the string, as well as the string itself.
  • For example, if a user wants each sequence to be generated with 5 digits, and with the number '0' prefixed for every digit that isn't generated by the base counter, I would write ${counter:padStart(5,0) where '5' is the number of digits in the string, and the '0' appearing for each number in the string.
  • I want to generate a list of all my sequences, in order of creation I can set a custom ID of ${seqName}_${counter:padStart(5,0)}, which would appear as "Sequence 1_00001", "Sequence 2_00002", "Sequence 3_00003," etc.

 

Generator Syntax Table

Generator Element	Parameters	Output	Description	Applies To	Example
charId	None	String	Retrieves the Character CXID for dialogue element	Dialogue & Character	${charId}
charName	None	String	Retrieves the Character name for a dialogue element.	Dialogue & Character	${charName}
counter	None	String	Counter for each element/item which increases after initial generation. Does not check or update beyond the creation of a new element/item (i.e. deleting a sequence with a counter ID convention will not affect count).	Any	${seqName}_${counter}
cxId	None	String	Retrieves the CXID for any element.	Any	${cxId}
now	None	Date	Retrieves the current date. Can be paired with a date operator for specificity.	Any	${now}
randId	Length Refers to the desired number of alphanumeric characters. If no parameter is used, length defaults to 6 characters.	String	Generates a random alphanumeric ID of user-specified length length.	Any	${randId} $randId(5)}
randNum	Length Refers to the desired number of digits. If no parameter is used, length defaults to 6 digits.	String	Generates a random number of user-specified length	Any	${randNum} ${randNum(6)}
seqId	None	String	Retrieves the CXID of a sequence or the parent sequence associated with an element/item.	Any script element. Does not work for elements that can exist in multiple sequences, such as Characters and Breakdown items.	${seqId}
seqName	None	String	Retrieves the name of a sequence or the parent sequence associated with an element/item.	Any script element. Does not work for elements that can exist in multiple sequences, such as Characters and Breakdown items.	${seqName}

 

Operator Syntax Tables

There are three types of Operators: String Operators, Date Operators, and one (1) Universal Operator. 

String Operators

Operation	Parameters	Description	Example
lowerCase	None	Converts the string to lowercase.	${seqName:lowerCase} For a sequence named “START”, this operation would render it in the custom ID as “start”.
prefix	Value	Adds a prefix to the string.	${seqName:prefix(‘not_’)} For a sequence named “START”, this operation would render it in the Custom ID as “not_START”.
replaceSpace	Value	Replaces all spaces in the string with the provided value.	${seqName:replaceSpace(‘_’)} For a sequence named “Start Node”, this operation would render it in the Custom ID as “Start_Node”.
suffix	Value	Adds a suffix to the string.	${seqName:suffix(‘_not’)} For a sequence named “START”, this operation would render it in the Custom ID as “START_not”.
trim	None	Removes whitespace from both sides of the string	${seqName:trim} For a sequence named “ START ”, this operation would render it in the Custom ID as “START”.
truncate	Length	Truncates the string by the defined number of characters.	$seqName:truncate(5)} For a sequence named “STARTING”, this operation would render it in the Custom ID as “START”.
upperCase	None	Converts the string to upper case text.	${seqName:upperCase} For a sequence named “start”, this operation would render it in the custom ID as “START”.
padStart	Value	Prefixes a counter generated custom ID with a string as defined by the user	${counter:padStart(5,0)} Custom IDs generated here with an increment of 2, for example, would appear as 00002, 00004, 00006, etc. where '5' represents the total number of digits, and the '0' indicates what the prefix will be set as.

 

Date Operators

Operation	Parameters	Description	Example
day	Date	Retrieves the current day when paired with ‘now’ Generator.	${now:day} If the date is January 21st, 2021, the result would be “21”.
month	Date	Retrieves the current month when paired with ‘now’ Generator.	${now:month} For January, the result would be “1”.
str	Date	Converts the current date to a string when paired with the ‘now’ Generator.	${now:str} For January 21st, 2021, the result would be “01-21-2021” (mm-dd-yyyy).
year	Date	Retrieves the current year when paired with ‘now’ Generator.	${now:year} For 2021, the result would be “2021”.

 

Universal Operator (Default Value)

Operation	Parameters	Description	Example
defaultValue	Value	This Operator will add a defined default value to any output that results as empty or null.	${charName:upperCase:defaultValue(‘no_char’)} In this example, the convention is designed to create a Custom ID for dialogue that shows the dialogue’s character name in upper case. If for some reason the dialogue does not have a Character name, the defaultValue operator will add ‘no_char’ to the ID to prevent an empty or null ID field.