aseprite/docs/script.txt

                    ASE Scripting 0.4

                 By David A. Capello, 2005.



#include <std_disclaimer.h>

   "I do not accept responsibility for any effects, adverse or otherwise,
    that this code may have on you, your computer, your sanity, your dog,
    and anything else that you can think of. Use it at your own risk."



======================================
============ Introduction ============
======================================

  ASE has scripting facilities.  You can make a script (a text file)
  with a set of routines to make images, effects, or anything you
  think.  ASE uses Lua library to do this, so you should know program
  in Lua, anyway, it's really simple, so you'll not have any
  inconvenient.

  The complete reference of Lua language is in lua-5.0.pdf. Also, you
  need a text editor to write Lua scripts (the Windows Notepad can
  be used).

Warning about Lua
-----------------

  You should known that ASE uses a patched version of Lua, where you
  can use the != operator instead of ~=

    if current_sprite != nil then
      -- we can use the current_sprite variable...
    end



===============================================
============ Basic Lua Programming ============
===============================================

Comments
--------

  Comments start with --

    -- this line will be never parsed

  Or you can comment multiple lines

    --[[
    blah blah blah...
    ]]--

Example 1
---------

    local a = 4
    local b = 5
    print ("a+b is: " .. (a+b))


  Here we define two variables "a" and "b" with the values "4" and "5"
  respectively.  Then we print the string "a+b is: " follower by the
  result of the operation a+b (4+5) that is 9, so the final message is:

    a+b is: 9

  Also we could use:

    print (a.."+"..b.." is: "..(a+b))

  To print:

    4+5 is: 9

Example 2
---------

    function add (a, b)
      return a+b
    end
    print ("1+2 = " .. add (1, 2))

  With the "function" keyword you define a new function, in this case
  the "add" function, the names between parenthesis indicate the
  arguments (parameters) that you must give to that routine.

Example 3
---------

    for c = 1, 10 do
      print (c)
    end

  This repeat the block between the "do" keyword and the "end" keyword
  10 times (from 1 to 10 inclusive).

  So this print:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

Example 4
---------

    for c = 1, 10 do
      if c == 5 then
        break
      end
      print (c)
    end

  In this case when "c" come to 5 the for is breaked so the other
  iterations aren't made.  This print:

    1
    2
    3
    4

Example 5
---------

    for c = 1, 5 do
      if c != 3 then
        print ("c isn't 3 (c is " .. c .. ")")
      else
        print ("c is 3")
      end
    end

  The != operator means "not equal" (negation of equality).  You can
  use the original Lua operator ~= too.

  This print:

    c isn't 3 (c is 1)
    c isn't 3 (c is 2)
    c is 3
    c isn't 3 (c is 4)
    c isn't 3 (c is 5)

Example 6
---------

    local done = false
    local a = 1
    while not done do
      print (a)
      if a == 3 then
        done = true
      end
      a = a + 1
    end

  This print:

    1
    2
    3

  And can be implemented in this way too:

    local a = 1
    while a <= 3 do
      print (a)
      a = a + 1
    end



=================================
============ ImgType ============
=================================

  The imgtype (image-type) is the format of each pixel in a image.
  Sprites have a lot of images, but all images must have the same
  imgtype. The know imgtypes are: RGB, Grayscale, Indexed, Bitmap.

IMAGE_RGB
---------

  Means that the image have four components (channels or bytes) per
  pixel, where the values of these components can be between 0 and 255
  (256 differents tones), where 255 the maximum intensity.

  RGB is RGBA really:

    R: Red.

    G: Green.

    B: Blue.

    A: Alpha (transparency or opacity).

  (0,0,0,0) is mask color, (0,0,0,255) is black, and (255,255,255,255)
  is white.

IMAGE_GRAYSCALE
---------------

  The image has two channels (two bytes) per pixel.

    K: Luminance (or black channel)

    A: Alpha (transparency or opacity).

  (0,0) is mask color, (0,255) is black, (255,255) is white.

IMAGE_INDEXED
-------------

  Image uses one byte per pixel:

    Index: index of the color that we must use from the color-palette.


  In this imgtype, each pixel hasn't the color information, only has a
  reference to the color-palette (from 0 to 255, 256 colors), so the
  RGB information about the color is found in the color-palette and
  not in the image.

  The index=0 is the mask color.

IMAGE_BITMAP
------------

  An internal imgtype to handle masks, where a pixel is a bit, and 8
  pixels are a byte. 1 means selected, 0 deselected.



===========================================
============ Standard routines ============
===========================================

double MAX (double x, double y);
  Returns the maximum value.

double MIN (double x, double y);
  Returns the minimum value.

double MID (double x, double y, double z);
  Limits the y value to x and z. 

void include (const char *filename);
void dofile (const char *filename);
  Process the script that is in the file with the given filename. It's
  searched in the current and in the "data/scripts" directories.

void print (const char *buf);
  Prints a message in the console, this is useful mainly to debug
  scripts or to show errors.

double rand (double min, double max);
  Returns a random number between min and max values.



=========================================
============ String routines ============
=========================================

const char *_ (const char *msgid);
  Tries to translate the string msgid to the current language, the
  entry must exists in the .po file.

int strcmp (const char *s1, const char *s2);
  Compares the two strings s1 and s2. It returns an integer less than,
  equal to, or greater than zero if s1 is found, respectively, to be
  less than, to match, or be greater than s2.



=======================================
============ Math routines ============
=======================================

Constants
---------

  PI: the ratio of a circle's circumference to its diameter (3.141592...).

Routines
--------

double fabs (double x);
  Return the absolute value of the number x.

double ceil (double x);
  This funtion rounds x up to the nearest integer.

double floor (double x);
  This funtion rounds x down to the nearest integer.

double exp (double x);
  Returns the value of e (the base of natural logarithms) raised to
  the power of x.

double log (double x);
  Returns the natural logarithm of x.

double log10 (double x);
  Returns the base-10 logarithm of x.

double pow (double x, double y);
  Returns the value of x raised to the power of y.

double sqrt (double x);
  Returns the non-negative square root of x.

double hypot (double x, double y);
  Returns the sqrt(x*x + y*y).  This is the length of the hypotenuse
  of a right-angle triangle with sides of length x and y, or the
  distance of the point (x, y) from the origin.

double cos (double x);
  Returns the cosine of x, where x is given in radians.

double sin (double x);
  Returns the sine of x, where x is given in radians.

double tan (double x);
  Returns the tangent of x, where x is given in radians.

double acos (double x);
  Returns the arc cosine in radians and the value is mathematically
  defined to be between 0 and PI (inclusive).

double asin (double x);
  Returns the arc sine in radians and the value is mathematically
  defined to be between -PI/2 and PI/2 (inclusive).

double atan (double x);
  Returns the arc tangent in radians and the value is mathematically
  defined to be between -PI/2 and PI/2 (inclusive).

double atan2 (double y, double x);
  Returns the result in radians, which is between -PI and PI
  (inclusive).

double cosh (double x);
  Returns the hyperbolic cosine of x, which is defined mathematically
  as (exp(x) + exp(-x)) / 2.

double sinh (double x);
  Returns the hyperbolic sine of x, which is defined mathematically as
  (exp(x) - exp(-x)) / 2.

double tanh (double x);
  Returns the hyperbolic tangent of x, which is defined mathematically
  as sinh(x) / cosh(x).



=======================================
============ File routines ============
=======================================

bool file_exists (const char *filename);
  Checks whether a file matching the given name exists, returning true
  if it does.

char *get_filename (const char *filename);
  When passed a completely specified file path, this returns a pointer
  to the filename portion. Both <20>\<5C> and <20>/<2F> are recognized as directory
  separators.
  


=================================
============ Objects ============
=================================

  There are a special type of variables in Lua scripts: objects
  (represented with user-data).  Each object can be of some of these
  types:

  Graphics objects: Image, Frame, Layer, Mask, Path, Sprite, Stock, Undo.

  Effect objects: Effect, ConvMatr, Curve, CurvePoint.

  GUI objects: JEvent, JList, JRect, JRegion, JWidget.



===============================
============ Image ============
===============================

  An image, has width and height, an image-type (RGB, Grayscale, etc.),
  and contains the image data (pixels, pixmap, or bitmap).

Image fields
------------

  [number] image.imgtype
    See sprite.imgtype

  [number] image.w
  [number] image.h
    The width and height (in pixels) of this image.

Image methods
-------------

Image *image_new (int imgtype, int w, int h);
  Creates a new image

Image *image_new_copy (Image *image);

void image_free (Image *image);

int image_getpixel (Image *image, int x, int y);

void image_putpixel (Image *image, int x, int y, int color);

void image_clear (Image *image, int color);

void image_copy (Image *dst, Image *src, int x, int y);

void image_merge (Image *dst, Image *src, int x, int y, int opacity, int blend_mode);

Image *image_crop (Image *image, int x, int y, int w, int h);

void image_hline (Image *image, int x1, int y, int x2, int color);

void image_vline (Image *image, int x, int y1, int y2, int color);

void image_rect (Image *image, int x1, int y1, int x2, int y2, int color);

void image_rectfill (Image *image, int x1, int y1, int x2, int y2, int color);

void image_line (Image *image, int x1, int y1, int x2, int y2, int color);

void image_ellipse (Image *image, int x1, int y1, int x2, int y2, int color);

void image_ellipsefill (Image *image, int x1, int y1, int x2, int y2, int color);
                        
void image_convert (Image *dst, Image *src);

int image_count_diff (Image *i1, Image *i2);



===============================
============ Frame ============
===============================

  A frame of animation, it contains the position, opacity and a reference
  (by index) to some image in the image's stock of the layer where this
  frame is. Remember this, a frame doesn't contain the image, only a
  reference to it.

Frame *frame_new (int frpos, int image, int x, int y, int opacity);

Frame *frame_new_copy (Frame *frame);

void frame_free (Frame *frame);

Frame *frame_is_link (Frame *frame, Layer *layer);
 
void frame_set_frpos (Frame *frame, int frpos);

void frame_set_image (Frame *frame, int image);

void frame_set_position (Frame *frame, int x, int y);

void frame_set_opacity (Frame *frame, int opacity);



===============================
============ Layer ============
===============================

  A layer can be two things: a normal layer (also called image layer),
  or a layer set.  A layer set is a group of child layers (like
  "sprite.set").  A normal layer is a complete different thing.

  A normal layer has a stock of images and a list of frames, each
  frame has a reference to the image's stock, so each frame uses some
  image of the stock.  If two frames uses the same stock images, the
  first frame is called the "original frame" and all other frames are
  called "links".

Layer *layer_new (int imgtype);

Layer *layer_set_new (void);

Layer *layer_new_copy (Layer *layer);

Layer *layer_new_with_image (int imgtype, int x, int y, int w, int h,
                             int frpos);

void layer_free (Layer *layer);

bool layer_is_image (Layer *layer);

bool layer_is_set (Layer *layer);

Layer *layer_get_prev (Layer *layer);

Layer *layer_get_next (Layer *layer);

void layer_set_name (Layer *layer, const char *name);

void layer_set_blend_mode (Layer *layer, int blend_mode);

void layer_add_frame (Layer *layer, Frame *frame);

void layer_remove_frame (Layer *layer, Frame *frame);

Frame *layer_get_frame (Layer *layer, int frpos);

void layer_add_layer (Layer *set, Layer *layer);

void layer_remove_layer (Layer *set, Layer *layer);

void layer_move_layer (Layer *set, Layer *layer, Layer *after);

void layer_render (Layer *layer, Image *image, int x, int y, int frpos);

Layer *layer_flatten (Layer *layer, int imgtype, int x, int y, int w, int h,
                      int frmin, int frmax);



==============================
============ Mask ============
==============================

Mask *mask_new (void);

Mask *mask_new_copy (Mask *mask);

void mask_free (Mask *mask);

bool mask_is_empty (Mask *mask);

void mask_set_name (Mask *mask, const char *name);

void mask_move (Mask *mask, int x, int y);

void mask_none (Mask *mask);

void mask_invert (Mask *mask);

void mask_replace (Mask *mask, int x, int y, int w, int h);

void mask_union (Mask *mask, int x, int y, int w, int h);

void mask_subtract (Mask *mask, int x, int y, int w, int h);

void mask_intersect (Mask *mask, int x, int y, int w, int h);

void mask_merge (Mask *dst, Mask *src);

void mask_by_color (Mask *mask, Image *image, int color, int fuzziness);

void mask_crop (Mask *mask, Image *image);



==============================
============ Path ============
==============================

Path *path_new (const char *name);

void path_free (Path *path);

void path_set_join (Path *path, int join);

  PATH_JOIN_MITER

  PATH_JOIN_ROUND

  PATH_JOIN_BEVEL


void path_set_cap (Path *path, int cap);

  PATH_CAP_BUTT

  PATH_CAP_ROUND

  PATH_CAP_SQUARE


void path_moveto (Path *path, double x, double y);

void path_lineto (Path *path, double x, double y);

void path_curveto (Path *path, double control_x1, double control_y1, double control_x2, double control_y2, double end_x, double end_y);

void path_close (Path *path);

void path_move (Path *path, double x, double y);

void path_stroke (Path *path, Image *image, int color, double brush_size);

void path_fill (Path *path, Image *image, int color);



================================
============ Sprite ============
================================

  The sprite is the main object of ASE (remember Allegro "Sprite"
  Editor), and it's the structure that contains all data: layers,
  frames, stocks, images, masks, paths, and undo information are
  inside the same sprite.

  There are a global variable of Sprite type: current_sprite.  This
  could be "nil" if there aren't a selected sprite in the moment.

  You should known about the difference between the "current_sprite"
  in scripts and the sprite in the current editor.  Because when you
  select a sprite with "set_current_sprite", only the "current_sprite"
  global pointer is set, but the sprite in the current editor is
  maintain intact.  So when ASE runs a script, the "current_sprite"
  will be pointing to the sprite in the current editor, but if you
  change the "current_sprite" (with "set_current_sprite" routine)
  you'll not get that sprite in the editor (use "sprite_show" function
  instead).

Sprite *sprite_new (int imgtype, int w, int h);

Sprite *sprite_new_copy (Sprite *sprite);

Sprite *sprite_new_flatten_copy (Sprite *sprite);

Sprite *sprite_new_with_layer (int imgtype, int w, int h);

void sprite_free (Sprite *sprite);

void sprite_lock (Sprite *sprite);

void sprite_unlock (Sprite *sprite);

bool sprite_is_locked (Sprite *sprite);

bool sprite_is_modified (Sprite *sprite);

void sprite_was_saved (Sprite *sprite);

void sprite_set_filename (Sprite *sprite, const char *filename);

void sprite_set_size (Sprite *sprite, int w, int h);

void sprite_set_frames (Sprite *sprite, int frames);

void sprite_set_speed (Sprite *sprite, int speed);

void sprite_set_path (Sprite *sprite, Path *path);

void sprite_set_mask (Sprite *sprite, Mask *mask);

void sprite_set_layer (Sprite *sprite, Layer *layer);

void sprite_set_frpos (Sprite *sprite, int frpos);

void sprite_set_imgtype (Sprite *sprite, int imgtype, int dithering_method);

void sprite_add_path (Sprite *sprite, Path *path);

void sprite_remove_path (Sprite *sprite, Path *path);

void sprite_add_mask (Sprite *sprite, Mask *mask);

void sprite_remove_mask (Sprite *sprite, Mask *mask);

Mask *sprite_request_mask (Sprite *sprite, const char *name);

void sprite_render (Sprite *sprite, Image *image, int x, int y);



===============================
============ Stock ============
===============================

  Stock of images.  Each image layer has its own image's stock to
  provide images to its frames.

Stock *stock_new (int imgtype);

Stock *stock_new_copy (Stock *stock);

void stock_free (Stock *stock);

int stock_add_image (Stock *stock, Image *image);

void stock_remove_image (Stock *stock, Image *image);

void stock_replace_image (Stock *stock, int index, Image *image);

Image *stock_get_image (Stock *stock, int index);



==============================
============ Undo ============
==============================

Undo *undo_new (Sprite *sprite);

void undo_free (Undo *undo);

void undo_enable (Undo *undo);

void undo_disable (Undo *undo);

bool undo_is_enabled (Undo *undo);

bool undo_is_disabled (Undo *undo);

bool undo_can_undo (Undo *undo);

bool undo_can_redo (Undo *undo);

void undo_undo (Undo *undo);

void undo_redo (Undo *undo);

void undo_open (Undo *undo);

void undo_close (Undo *undo);

void undo_image (Undo *undo, Image *image, int x, int y, int w, int h);

void undo_flip (Undo *undo, Image *image, int x1, int y1, int x2, int y2,
                int horz);

void undo_add_image (Undo *undo, Stock *stock, Image *image);

void undo_remove_image (Undo *undo, Stock *stock, Image *image);

void undo_replace_image (Undo *undo, Stock *stock, int index);

void undo_add_frame (Undo *undo, Layer *layer, Frame *frame);

void undo_remove_frame (Undo *undo, Layer *layer, Frame *frame);

void undo_add_layer (Undo *undo, Layer *set, Layer *layer);

void undo_remove_layer (Undo *undo, Layer *layer);

void undo_move_layer (Undo *undo, Layer *layer);

void undo_set_layer (Undo *undo, Sprite *sprite);

void undo_set_mask (Undo *undo, Sprite *sprite);



================================
============ Effect ============
================================

Effect *effect_new (Sprite *sprite, const char *name);

void effect_free (Effect *effect);

void effect_load_target (Effect *effect);

void effect_set_target (Effect *effect, bool r, bool g, bool b, bool k, bool a, bool index);

void effect_set_target_rgb (Effect *effect, bool r, bool g, bool b, bool a);

void effect_set_target_grayscale (Effect *effect, bool k, bool a);

void effect_set_target_indexed (Effect *effect, bool r, bool g, bool b, bool index);

void effect_begin (Effect *effect);

void effect_begin_for_preview (Effect *effect);

int effect_apply_step (Effect *effect);

void effect_apply (Effect *effect);

void effect_flush (Effect *effect);

void effect_apply_to_image (Effect *effect, Image *image, int x, int y);

void effect_apply_to_target (Effect *effect);



==================================
============ ConvMatr ============
==================================

ConvMatr *convmatr_new (int w, int h);

ConvMatr *convmatr_new_string (const char *format);

void convmatr_free (ConvMatr *convmatr);

Convolution Matrix Effect
-------------------------

void set_convmatr (ConvMatr *convmatr);

ConvMatr *get_convmatr (void);

ConvMatr *get_convmatr_by_name (const char *name);



===============================
============ Curve ============
===============================

  Curve is a type to represent a function y=f(x). It's mainly used in
  color-curve effect.

Curve *curve_new (int type);
  Creates a new curve, type can be CURVE_LINEAR or CURVE_SPLINE.

void curve_free (Curve *curve);

void curve_add_point (Curve *curve, CurvePoint *point);

void curve_remove_point (Curve *curve, CurvePoint *point);

Color Curve Effect
------------------

void set_color_curve (Curve *curve);



====================================
============ CurvePoint ============
====================================

CurvePoint *curve_point_new (int x, int y);

void curve_point_free (CurvePoint *point);



================================
============ JEvent ============
================================



===============================
============ JList ============
===============================



===============================
============ JRect ============
===============================

JRect fields
------------

  [number] rect.x
  [number] rect.y
    Position of the upper-left corner of the rectangle.

  [number] rect.w
  [number] rect.h
    Size of the rectangle (width and height).




=================================
============ JRegion ============
=================================



=================================
============ JWidget ============
=================================