Hotspot Script Syntax (umx_hotspot)

Full syntax reference for the umx_hotspot script, which creates and edits hotspot layout assets.

umx_hotspot creates and edits hotspot layout assets from a single script. For what hotspot texturing itself does, see Hotspot Texturing.

asset "Assets/Hotspots/Walls.asset" create
new "TrimTop" rect=0,0.75,1,1
  rule axis type=topside angle=15
grid cols=2 rows=2 pad=0.01 prefix="Cell"
list

Statements

Statement	What it does
`asset "path" [create]`	Select the asset the following lines apply to
`new ["name"] rect=...`	Create a layout
`@"name"` / `@#index`	Edit an existing layout
`rule <kind> ...`	Apply a rule to the layout above (2-space indent)
`del "name"` / `del #index`	Delete a layout
`clear`	Delete all layouts
`grid cols=N rows=M`	Split the 0..1 UV square into a grid
`export "path.png"`	Save a color guide PNG
`list`	Include a layout snapshot in the result

The basic rules (2-space indentation, # comments, quoted names, period decimals) are the same as in the scene script.

Selecting the target asset (asset)

asset "Assets/Hotspots/Walls.asset"
asset "Assets/Hotspots/Walls.asset" create

The path must start with Assets/ and end with .asset.
Adding create creates the asset when it does not exist. Without it, only an existing asset is targeted.
With no asset line at all, the active hotspot of the open Hotspot Editor is used.

You can use several asset lines in one script to edit several assets in sequence.

Creating layouts (new)

new "TrimTop" rect=0,0.75,1,1
new rect=0,0,0.5,0.5

rect=minU,minV,maxU,maxV is required, and min must be less than max.
The name may be omitted.
No k=v keys other than rect are accepted.

Editing layouts (@)

@"Cell_0_0" name="Floor"
@"Floor" rect=0,0,1,0.25
@#12 name="TrimBottom"

Target with @"name" or @#index, where #index is the layout index.
name= renames it and rect= changes its area. No other keys are accepted.
rule lines may be indented underneath to set rules at the same time.

Rules (rule)

rule may only appear indented by 2 spaces under a new or @ line. Indenting anything other than a rule is an error.

rule axis — restrict by face direction

rule axis type=topside angle=15
rule axis off

Key	Values
`type`	`top` · `bottom` · `side` · `topbottom` · `topside` · `bottomside`
`angle`	Allowed angle in degrees

rule length — restrict by size

rule length min=0.1,0.1 max=0.5,0.5
rule length max=1,1

Key	Values
`min`	two components, `u,v`
`max`	two components, `u,v`

rule uvdirect — restrict by UV direction

rule uvdirect allow=x+,x-,y+

Key	Values
`allow`	one or more of `x+` `x-` `y+` `y-` `z+` `z-`, comma-separated

Turning a rule off

Use an off token in place of the values to disable the rule.

rule axis off
rule length off
rule uvdirect off

Deleting (del · clear)

del "TrimTop"
del #12
clear

clear removes every layout from the target asset.

Grid splitting (grid)

grid cols=4 rows=2
grid cols=2 rows=2 pad=0.01 prefix="Cell"

Splits the 0..1 UV square into cols × rows layouts in one statement.

Key	Description	Default
`cols`	Column count (required)	—
`rows`	Row count (required)	—
`pad`	UV gap between cells	0
`prefix`	Name prefix	—

Names follow {prefix}_{row}_{col} — for example Cell_0_0.

Exporting a guide image (export)

export "D:/out/walls_guide.png"
export "D:/out/walls_guide.png" res=2048

Saves a guide PNG that color-codes the layout arrangement, useful as a base when painting the texture.

The path must end with .png, and the destination folder must exist.
Allowed res values: 512 · 1024 · 2048 · 4096

Inspecting the current state (list)

list

Includes a layout snapshot (index, name, rect, rules) in the result data. Useful for checking the current state before deciding on the next edit.

Result data

Field	Contents
`created`	Created layouts (`"Name#index"`)
`updated`	Updated layouts
`deleted`	Deleted layouts
`rulesApplied`	Number of rules applied
`failed`	Failed statements — line number and reason
`warnings`	Warning list
`layouts`	The layout snapshot, when `list` was used

#index works anywhere "name" does — @#index, del #index.

Full example

# A trim sheet layout for walls and floors
asset "Assets/Hotspots/Walls.asset" create
clear

new "TrimTop" rect=0,0.75,1,1
  rule axis type=topside angle=15
  rule length min=0.1,0.1 max=0.5,0.5
  rule uvdirect allow=x+,x-,y+

new "WallLarge" rect=0,0.25,0.5,0.75
  rule axis type=side angle=20

new "Floor" rect=0.5,0.25,1,0.75
  rule axis type=top angle=10

export "D:/out/walls_guide.png" res=2048
list

When starting from a grid, it is easier to create the cells first and then adjust names and rules.

asset "Assets/Hotspots/Tileset.asset" create
clear
grid cols=4 rows=4 pad=0.005 prefix="Cell"
@"Cell_0_0" name="Floor"
  rule axis type=top angle=10
list