Script editor

Last update: v1.10.0 - See also: Particle editor | CParticleEvolver_Script | Script reference

The script editor is the main editor panel where you edit PopcornFX scripts.
It colors each script line based on its final runtime performance so you can quickly see which parts of your script cost the most.

Overview

The script editor is split in 5 main tabs:

• The 'Source' tab is where you edit the scripts
• The 'Parsed' tab is the script re-generated from its compiled version. It shows how the script compiler understood and transformed your script
• The 'Externals' tab is a debug tab showing the data-binding details: which particle fields, attributes, and samplers your script is accessing.
• The 'Disassembly' tab shows the final instructions generated by the script compilation, this is what will get executed.
• The 'Bytecode' tab shows the final compact bytecode produced at the end of the compilation chain (its only purpose is to help developers debug)

Source tab

Main edition area.

In addition to standard editing commands like backspace/delete, the following shortcuts are available:

• [Ctrl]+[S] : compile script & save (warning: saves the whole effect)
• [Ctrl]+[Enter] : compile script (doesn't save the effect)
• [Ctrl]+[Z] : Undo
• [Ctrl]+[Y] : Redo
• [Ctrl]+[C] : Copy
• [Ctrl]+[X] : Cut
• [Ctrl]+[V] : Paste
• [Ctrl]+[F] : Find/Replace dialog
• [Tab] / [Shift]+[Tab] : Ident Right / Left
• [Ctrl]+[Delete] : delete whole word right
• [Ctrl]+[Backspace] : delete whole word left

You can also right-click in the text and insert a color through the "Insert color" menu (pops a color-picker dialog)

Parsed tab

Shows how the script compiler understood your script.

Externals tab

Shows what external data your script accesses ( fields, attributes, samplers, spatial layers)

Column detail:

• TypeID : Internal (developer debug)
• Name : Name of the external data source
• NID : Internal (developer debug)
• bytes : footprint in bytes of the data element
• MetaType : variability of the data
  • Constant : compile-time
  • Normal : varies at most per-frame ( spatial layers, samplers)
  • Instance : varies at most for each FX instance ( attributes, attribute samplers)
  • Stream : varies at most per-particle ()
• Type : type of one data element

Disassembly tab

final instructions generated by the script compilation, this is what will get executed.

Column detail:

• MetaType : variability of the data, identical to the 'MetaType' column in the 'Externals' tab
  • Constant : compile-time
  • Normal : varies at most per-frame ( spatial layers, samplers)
  • Instance : varies at most for each FX instance ( attributes, attribute samplers)
  • Stream : varies at most per-particle ()
• Cycles : CPU cycles measured from script execution, used to color-code the instruction, and the lines in the 'Source' tab. You can see this as a measure of time spent executing that instruction.
• Instruction : Actual instruction. Syntax: <destination_register> = <opcode> <list_of_input_registers>

Bytecode tab

final compact bytecode produced at the end of the compilation chain (its only purpose is to help developers debug)

Performance indicators

Each line in the main editing area and in the 'disassembly' tab is colored based on performance.

v1.10.0
Before v1.10.0, these performance numbers were static estimates (that were completely wrong most of the time)
Since v1.10.0, they are fed actual profiling numbers, the editor times the execution of the script in real time as the effect runs in your viewport, and colors the script based on the real performance cost of each line/instruction.

Cheap lines are colored light-green, costly lines are colored red. This allows to quickly spot bottlenecks in a script.
Note that if you split a computation into many lines, each line will appear cheap, but due to a large number of lines, the computation will still be costly.

Line 14&15: high performance impact you should try simplifying if possible
Line 14&15: medium performance impact
Line 14&15: small/normal cost

Status panel

The status panel gives information about the compilation of the script.

In its minimized state, it will tell you if the script was successfully built or not.
If the script was build successfully, a success message will be displayed in green.
Otherwise, an error message will be displayed in red.

By clicking on the status bar, you can unroll the status panel, and see more detailed informations.

If a build succeeded, you will see a condensed build report displaying instruction count, flat and streamed meta-cycles.
Meta-cycles are the virtual cost of a meta-instruction given to the hh-compiler backend, they are a rough estimate of the cost of that instruction on the final hardware.
The higher the number of meta-cycles an instruction has, the more costly it is to execute at runtime.

Build panel after a successful build

If there is an error in the script, and compilation fails, the build panel will contain details about what caused the error:

Here, we misspelled the local variable 'hitToPos', and wrote 'hitToPoss' instead. We get an error message telling us the symbol 'hitToPoss' doesn't exist.