- Placeholder names are case sensitive and follow the same snake_case keys that appear in the UI tooltips and configuration files.
- Brackets (`[]`) mark vector-valued options. Extruder-scoped vectors default to the *currently active* extruder when no index is provided; specify a zero-based index (`bed_temperature[1]`) to query another tool. Object or plate-scoped arrays always require an explicit zero-based index.
- Unless noted otherwise distances are in millimetres, temperatures in °C, volumes in mm³, weights in grams, feedrates in mm/min, and booleans return `0`/`1`.
- Points and bounding boxes are stored as `[x, y]` pairs expressed in mm.
-`layer_num` is one-based (first layer is `1`). All other indices use zero-based numbering.
- Every print/filament/printer setting is also available under its config key. Hover the label in the UI to see the key or check the Variable in the Wiki description. The tables below focus on additional runtime placeholders.
Basic math operators (`+`, `-`, `*`, `/`) and parentheses are supported for numeric placeholders, allowing you to do simple calculations. For example, `{used_filament/1000}m` converts filament usage to meters.
C++ functions can be used as long as they are not from a library to be included, such as `cmath`.
- Rounding: can be done using `int()`, for example `{int(total_weight*10) / 10.0}g`. `round()`: **cannot** be used because it is a function from the cmath library.
| `position[]` | float[3] (mm) | XYZ position of the tool when control entered the custom block. Update this if you move the tool so the slicer keeps continuity. |
| `e_position[]` | float per extruder (mm) | Absolute extruder axis position, used only when the G-code uses absolute E coordinates. |
| `e_retracted[]` | float per extruder (mm) | Retraction state at block entry. Update when you manually retract or unretract so OrcaSlicer can compensate afterwards. |
| `e_restart_extra[]` | float per extruder (mm) | Planned extra priming after the next de-retraction. |
Timestamp components information recorded when slicing began.
| Placeholder | Type | Description |
| --- | --- | --- |
| `timestamp` | string (`yyyyMMdd-hhmmss`) | Local timestamp captured when slicing ran. |
| `year` / month / day | int | Gregorian date components of `timestamp`. |
| `hour` / minute / second | int | Time-of-day components of `timestamp`. |
Any shell environment variable whose name starts with `SLIC3R_` is also imported as a placeholder under the same key, allowing you to pass ad-hoc values into a slice (for example `SLIC3R_BUILD_TAG`).
Notes about the limited placeholder set that is available when OrcaSlicer builds the export filename.
The slicer resolves `filename_format`**before** any G-code is produced (see `Print::output_filename`).
Only placeholders that are already present in the global parser at that time can be used in the exported file name:
- Configuration keys from the active print/filament/printer presets, including `print_preset`, `filament_preset[]`, `printer_preset`, and every regular setting (line widths, temperatures, etc.).
- Object metadata injected up front: `input_filename`, `input_filename_base`, `num_objects`, `num_instances`, `scale[]`, `plate_name`, `model_name`, plus the timestamp and user placeholders.
- Print statistics computed right after slicing such as `print_time`, `normal_print_time`, `silent_print_time`, `used_filament`, `extruded_volume`, `total_cost`, `total_toolchanges`, `total_weight`, and wipe-tower totals.
Placeholders that are populated later, during per-layer or per-tool G-code generation, are **not** available inside `filename_format`. This includes everything under *Global Slicing State*, *Slicing State*, *Layer-aware*, *Toolchange*, *Filament start/end*, *Timelapse*, *Extrusion role*, and *Pause/color change helpers*. Using them in templates causes filename evaluation to fail because they are unset when the template is processed.
Runtime-only placeholders injected right before specific custom G-code hooks are evaluated.
In addition to the global placeholders above, OrcaSlicer injects context-specific values when it evaluates individual G-code macros.
### Layer-aware placeholders
| Placeholder | Type | Description |
| --- | --- | --- |
| `layer_num` | int (1-based) | Current layer index. Provided to `before_layer_change_gcode`, `layer_change_gcode`, `timelapse_gcode`, `wrapping_detection_gcode`, `change_filament_gcode`, `filament_start_gcode`, `filament_end_gcode`, and `machine_end_gcode`. |
| `layer_z` | float (mm) | Height of the top of the current layer (after applying any Z offset). Available in the same contexts as `layer_num`. |
| `max_layer_z` | float (mm) | Z height of the final layer. Available anywhere a layer-aware macro runs (layer change, timelapse, wrapping detection, change filament, filament start/end, machine end). |
| `filament_extruder_id` | int | Zero-based ID of the extruder whose macro is executing. Provided to filament start/end scripts, machine end G-code, change filament/path scripts, and other macros that need to know the current tool. |
### Toolchange and wipe tower placeholders
The following placeholders are populated only while `change_filament_gcode` (and the wipe-tower driven toolchange flow) is being evaluated.
| Placeholder | Type | Description |
| --- | --- | --- |
| `previous_extruder` / `next_extruder` | int | IDs of the extruder being unloaded and the one being loaded. |
| `toolchange_z` | float (mm) | Actual Z height at the moment the toolchange macro is called. |
| `outer_wall_volumetric_speed` | float (mm³/s) | Volumetric speed limit for the new extruder’s outer walls. |
| `relative_e_axis` | bool | Indicates whether the slicer is emitting relative E moves (`G91 E`). |
| `toolchange_count` | int | Number of tool changes that have occurred so far. |
| `fan_speed` | int | Legacy placeholder kept for compatibility (always `0`). |
| `old_retract_length` / `new_retract_length` | float (mm) | Retraction distance for the outgoing and incoming filaments. |
| `old_retract_length_toolchange` / `new_retract_length_toolchange` | float (mm) | Toolchange-specific retraction distances for each filament. |
| `old_filament_temp` / `new_filament_temp` | int (°C) | Requested nozzle temperatures before and after the toolchange. |
| `old_filament_e_feedrate` / `new_filament_e_feedrate` | int (mm/min) | Extrusion feedrates derived from volumetric limits for the old/new filaments. |
| `x_after_toolchange` / `y_after_toolchange` / `z_after_toolchange` | float (mm) | Position the slicer expects after the toolchange macro finishes. Update them if you move somewhere else. |
| `first_flush_volume` / `second_flush_volume` | float (mm of filament) | Each half of the planned purge length. |
| `flush_length` | float (mm of filament) | Total purge length requested for the toolchange. |
| `flush_length_1` … `flush_length_4` | float (mm of filament) | Individual purge segments (unused entries are `0`). |
| `flush_volumetric_speeds[]` | float per extruder (mm³/s) | Calibration purge speeds associated with the flush sequence. |
| `flush_temperatures[]` | int per extruder (°C) | Temperatures to use for each stage of the flush sequence. |
| `wipe_avoid_perimeter` | bool | `true` when wipe tower travel avoidance is active for the change. |
| `wipe_avoid_pos_x` | float (mm) | X coordinate of the avoidance barrier used around the wipe tower. |
| `travel_point_1_x` / `travel_point_1_y` | float (mm) | First intermediate XY travel waypoint in object coordinates. |
All `layer_*` placeholders from the previous section are also available inside `change_filament_gcode`.
### Filament start/end placeholders
| Placeholder | Type | Description |
| --- | --- | --- |
| `filament_extruder_id` | int | ID of the filament whose start or end macro is executing. Present in `filament_start_gcode`, `filament_end_gcode`, and `machine_end_gcode`. |
| `retraction_distance_when_cut` | float (mm) | Cut-retraction distance for the active filament. Provided to `filament_start_gcode` (and as a global placeholder). |
| `long_retraction_when_cut` | bool | Whether the “long retraction when cut” behaviour is enabled for the active filament. Provided to `filament_start_gcode` and globally. |
`filament_start_gcode` and `filament_end_gcode` also receive the layer-aware placeholders listed earlier (`layer_num`, `layer_z`, `max_layer_z`).
### Timelapse and wrapping detection
| Placeholder | Type | Description |
| --- | --- | --- |
| `most_used_physical_extruder_id` | int | Physical extruder that prints most of the layer. Supplied to `timelapse_gcode` and `wrapping_detection_gcode`. |
| `curr_physical_extruder_id` | int | Physical extruder currently active when the macro runs. Provided to the same scripts as above. |
| `timelapse_pos_x` / `timelapse_pos_y` | int (mm) | XY coordinates selected for taking the snapshot. Available only inside `timelapse_gcode`. |
| `has_timelapse_safe_pos` | bool | Indicates whether a safe snapshot position was found. Available in `timelapse_gcode`. |
### Extrusion role changes
| Placeholder | Type | Description |
| --- | --- | --- |
| `extrusion_role` | string | Name of the extrusion role that the slicer is about to use (Perimeter, ExternalPerimeter, Support, etc.). Available in `change_extrusion_role_gcode`. |
| `last_extrusion_role` | string | Previous extrusion role before the transition. Available in `change_extrusion_role_gcode`. |
### Pause / color change helpers
| Placeholder | Type | Description |
| --- | --- | --- |
| `color_change_extruder` | int | Extruder index associated with a color-change (`M600`) event. Populated when OrcaSlicer triggers `machine_pause_gcode` for a color change. |
Use these tables as a reference when designing custom start/end sequences, toolchange macros, or template snippets. Combine them with preset-specific placeholders (e.g. `nozzle_temperature`, `filament_diameter`) to script advanced behaviours.
