Script editor

From PopcornFX
Jump to: navigation, search

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.


Script editor : 'Source' tab


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.


Script editor : 'Parsed' tab


Externals tab

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


Script editor : 'Externals' tab


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
  • Type : type of one data element


Disassembly tab

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


Script editor : 'Disassembly' tab


Column detail:

  • MetaType : variability of the data, identical to the 'MetaType' column in the 'Externals' tab
  • 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)


Script editor : 'Bytecode' tab


Performance indicators

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


NewIcon.png 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

ScriptEditor B High.png
Line 14&15:

medium performance impact

ScriptEditor B Med.png
Line 14&15:

small/normal cost

ScriptEditor B Low.png


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.


ScriptEditor 02.png
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:

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