API reference

The scriptable surface, organized by domain. Every entry below is a binding registered by the editor's pixel-stroke-scripting crate, with the arguments it takes.

Two styles appear, and each binding has exactly one: free functions, ps_name(...), and methods on the document handle the editor puts in every script's scope, ps.name(...) (layers, pixels and document size).

Rhai never turns an integer into a float for you, so parameters marked float need a decimal point: ps_filter_hue_shift(30.0), not ps_filter_hue_shift(30). Colors are hex strings, "#rrggbb" or "#rrggbbaa".

Brush stable

  • ps_brush_size(px): brush diameter in pixels.
  • ps_brush_opacity(amount): float, 0.0 to 1.0.
  • ps_brush_opacity_pct(pct): the same, as an integer 0 to 100.
  • ps_brush_spacing(fraction): float, gap between stamps as a fraction of the size.
  • ps_brush_pixel_perfect(on): true filters out diagonal doubles.
  • ps_brush_shape(name): "round", "square" or "custom".
  • ps_brush_symmetry(mode): "none", "horizontal", "vertical", "both", or "radial:N" for N-way radial symmetry.
  • ps_brush_pressure_curve(name): "linear", "ease_in", "ease_out" or "s_curve".
  • Getters: ps_brush_get_size(), ps_brush_get_opacity(), ps_brush_get_shape(), ps_brush_get_spacing(), ps_brush_get_pixel_perfect().

Filters stable

Each filter applies to the active layer (inside the selection, if there is one) and returns the number of pixels it changed.

  • ps_filter_blur(radius): gaussian.
  • ps_filter_box_blur(radius)
  • ps_filter_sharpen(amount): float, typically 0.5 to 2.0.
  • ps_filter_edge_detect(): Sobel edges.
  • ps_filter_emboss()
  • ps_filter_brightness(amount): float, -1.0 (black) to 1.0 (white).
  • ps_filter_contrast(amount): float, -1.0 (flat) upward.
  • ps_filter_saturation(amount): float multiplier, 0.0 is grayscale.
  • ps_filter_hue_shift(degrees): float.
  • ps_filter_desaturate()
  • ps_filter_invert(): color channels, alpha kept.
  • ps_filter_posterize(levels): levels per channel, at least 2.
  • ps_filter_threshold(level): black and white at a luma cutoff, 0 to 255.
  • ps_filter_pixelate(block): mosaic block size in pixels.
  • ps_filter_outline(thickness, color): outline around opaque pixels.
  • ps_filter_drop_shadow(dx, dy, blur, color)

Layers stable

Methods on ps. Layer indexes count from 0.

  • ps.layer_count()
  • ps.layer_add(name): returns the new layer's index.
  • ps.layer_select(index), ps.layer_active()
  • ps.layer_remove(index)
  • ps.layer_duplicate(index)
  • ps.layer_reorder(from, to)
  • ps.layer_merge_down(index)
  • ps.layer_flatten_visible()
  • ps.layer_name(index, name), ps.layer_get_name(index)
  • ps.layer_visible(index, on), ps.layer_get_visible(index)
  • ps.layer_locked(index, on), ps.layer_get_locked(index)
  • ps.layer_opacity(index, amount): float, 0.0 to 1.0. Read it back with ps.layer_get_opacity(index).
  • ps.layer_blend_mode(index, mode): "normal", "multiply", "screen", "overlay" or "add". Read it back with ps.layer_get_blend_mode(index).

Palette stable

  • ps_palette_new(name)
  • ps_palette_delete(name)
  • ps_palette_duplicate(name, new_name)
  • ps_palette_list(): array of palette names.
  • ps_palette_set_active(name)
  • ps_palette_active_name(), ps_palette_active_colors()
  • ps_palette_colors(name)
  • ps_palette_add_color(name, hex)
  • ps_palette_remove_color(name, index)
  • ps_palette_set_color(name, index, hex)
  • ps_palette_reorder(name, from, to)
  • ps_palette_sort(name, key): "hue" or "luminance".
  • ps_palette_load_gpl(name, gpl_text)
  • ps_palette_load_hex(name, hex_list)
  • ps_palette_save_gpl(name), ps_palette_save_hex(name)

Selection stable

  • ps_selection_rect(x, y, w, h)
  • ps_selection_ellipse(x, y, w, h): all four are floats.
  • ps_selection_wand(x, y, tolerance)
  • ps_selection_all()
  • ps_selection_invert()
  • ps_selection_clear()
  • ps_selection_bounds(): [x, y, w, h], or an empty array with no selection.
  • ps_selection_has(): true if anything is selected.
  • ps_selection_ants(on): toggle marching ants.

Artboard stable

  • ps_artboard_resize(w, h, anchor): canvas size. anchor 0 to 8 places the old content (0 top-left, 4 center, 8 bottom-right).
  • ps_artboard_crop(x, y, w, h)
  • ps_artboard_trim(): trim transparent borders.
  • ps_artboard_scale(w, h): scale the image to a new size.
  • ps_artboard_flip_h(), ps_artboard_flip_v()
  • ps_artboard_rotate_90(), ps_artboard_rotate_180(), ps_artboard_rotate_270()

Drawing stable

  • ps_draw_text(x, y, text, color, scale): pixel text on the active layer, with scale from 1 to 32.
  • ps.pixel_get(x, y): returns the hex color.
  • ps.pixel_set(x, y, hex)
  • ps.pixel_fill(x1, y1, x2, y2, hex)
  • ps.doc_width(), ps.doc_height(), ps.doc_name()
  • ps_ellipse_filled(on): whether the ellipse tool draws filled.

Animation stable

  • ps_timeline_add_frame(), ps_timeline_duplicate_frame(index), ps_timeline_delete_frame(index)
  • ps_timeline_goto_frame(index), ps_timeline_current_frame(), ps_timeline_frame_count()
  • ps_timeline_play(), ps_timeline_pause(), ps_timeline_stop()
  • ps_timeline_set_fps(fps)
  • ps_timeline_set_loop_mode(mode): "once", "loop" or "pingpong".
  • ps_timeline_reverse_range(from, to)
  • ps_timeline_add_tag(name, from, to, color), ps_timeline_remove_tag(name), ps_timeline_list_tags()
  • ps_onion_skin_enable(on)
  • ps_onion_skin_config(prev, next, opacity): frames shown before and after (0 to 16), and a float opacity.

State machines experimental

  • ps_state_machine_add_state(name, clip, loop_mode, speed): speed is a float.
  • ps_state_machine_add_transition(from, to, condition_json, blend_ms): condition_json is an input with one of bool_eq, float_gt, float_lt, float_eq or trigger. blend_ms is a float.
  • ps_state_machine_set_input(name, value): a bool, a number, or "trigger".
  • ps_state_machine_current_state()

Files stable

  • ps_file_save(name): returns the document as base64 .pxs and adds name to the recent list.
  • ps_file_open(data): loads a base64 .pxs (or a data: URL).
  • ps_file_export(format, options): "png", "jpeg", "gif" or "webp". Returns base64. Options is a map, e.g. #{ scale: 2 }, #{ source: "timeline" }.
  • ps_file_recent(): array of recent document names.
  • ps_atlas_pack_frames(max_w, max_h, padding, trim): a JSON report.
  • ps_atlas_export_png(max_w, max_h, padding, trim): the atlas as base64 PNG.
  • ps_atlas_export_json(max_w, max_h, padding, trim): the atlas metadata.

Editor stable

  • ps_undo(), ps_redo()
  • ps_grid_toggle(), ps_center_viewport()
  • ps_export_png(): the editor's own PNG export.
  • ps_run_script(path): queue one of the editor's bundled scripts, e.g. "scripts/animation/blink.rhai".

Coming next soon

  • ps_stamp_* family: capture a stamp from a selection, save to the drawer, scrub through animated stamps with the mousewheel.
  • keybind.* and cmd.* namespaces for customizable shortcuts and command-palette entries.