UModeler X MCPis live — model with an AI agent
UModeler X

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

StatementWhat it does
asset "path" [create]Select the asset the following lines apply to
new ["name"] rect=...Create a layout
@"name" / @#indexEdit an existing layout
rule <kind> ...Apply a rule to the layout above (2-space indent)
del "name" / del #indexDelete a layout
clearDelete all layouts
grid cols=N rows=MSplit the 0..1 UV square into a grid
export "path.png"Save a color guide PNG
listInclude 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
KeyValues
typetop · bottom · side · topbottom · topside · bottomside
angleAllowed 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
KeyValues
mintwo components, u,v
maxtwo components, u,v

rule uvdirect — restrict by UV direction

rule uvdirect allow=x+,x-,y+
KeyValues
allowone 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.

KeyDescriptionDefault
colsColumn count (required)—
rowsRow count (required)—
padUV gap between cells0
prefixName 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

FieldContents
createdCreated layouts ("Name#index")
updatedUpdated layouts
deletedDeleted layouts
rulesAppliedNumber of rules applied
failedFailed statements — line number and reason
warningsWarning list
layoutsThe 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
Hotspot Script Syntax (umx_hotspot) | UModeler X Manual