Juice FX : Live Scripting

This is the documentation for Juice FX's live scripting. The scripting is based in LUA, so you can use all the core of the language along with these extra functions and properties.

In case you need more help, please feel free to contact me on Twitter on @CodeManuPro


Everything that's written on simulate() function will be executed when a Simulate happens.
This can be used to to custom Burst animations or to setup variables to be then changed on update().
The code written on the update() function will be executed every frame.
The code written on the render_start() function will be executed the first frame of the rendering process.
The code written on the render() function will be executed every frame of the rendering process.
The code written on the render_end() function will be executed the last frame of the rendering process.
This event is used for the drawing process. Trying to draw things outside the draw_* functions will not work.
The code written on the draw_pre() function will be executed before the layers get drawn.
This event is used for the drawing process. Trying to draw things outside the draw_* functions will not work.
The code written on the draw_pre() function will be executed after the layers get drawn.

You can access all the 8 layers with layer[number].
Example: layer0.X = 100;
Returns the current layer's sprite.
Example: draw_sprite(layer0.sprite_index,0,64,64);
Change the X position of the layer.
Example: layer0.X = 100;
Change the Y position of the layer.
Example: layer0.Y = 100;
You can change the layer's width with xScale.
Example: layer0.xScale = random(10);
You can change the layer's height with yScale.
Example: layer0.yScale = random(10);
You can skew horizontally the layer with xSkew.
Example: layer0.xSkew = wave(-.5,.5,1,0);
You can skew vertically the layer with ySkew.
Example: layer0.ySkew = wave(-.5,.5,1,0);
Returns the real X value of the layer position.
This value is the X position as it's seen on the screen.
Example: draw_sprite(layer0.sprite_index,layer0.realX,layer0.realY);
Returns the real Y value of the layer position.
This value is the Y position as it's seen on the screen.
Example: draw_sprite(layer0.sprite_index,layer0.realX,layer0.realY);
Returns the real xScale value of the layer position.
This value is the xScale as it's seen on the screen, changing in Pixel Art and HD mode.
Example: draw_sprite_ext(layer0.sprite_index,layer0.realX,layer0.realY,layer0.realXScale,layer0.realYScale,0,-1,1);
Returns the real yScale value of the layer position.
This value is the yScale as it's seen on the screen, changing in Pixel Art and HD mode.
Example: draw_sprite_ext(layer0.sprite_index,layer0.realX,layer0.realY,layer0.realXScale,layer0.realYScale,0,-1,1);
You can rotate the layer with imageAngle.
Example: layer0.imageAngle = wave(0,360,2,0);
The number of frames for the layer to be flashing. Setting this to a constant number will keep the flash effect still.
Example: layer0.flashTimer = 10;
Changes the color of the flash effect.
Example: layer0.flashColor = c_red;
Changes the intensity of the flash effect.
Example: layer0.flashIntensity = 10;
Changes the mode of the flash effect. 0 = Normal, 1 = Additive.
Example: layer0.flashMode = 1;
The number of frames for the layer to be shaking. Setting this to a constant number will keep the shaking effect.
Example: layer0.shakeTimer = 10;
Changes the smoothness of the shake effect. Lower values give smoother effects.
Example: layer0.shakeSmooth = .2;
Changes the intensity of the shake effect.
Example: layer0.shakeIntensity = 10;
Changes the rotational amount of the shake effect.
Example: layer0.shakeRotational = 1;

Returns the x value with a easing function applied. x should be a number from 0 to 1.
All the functions from easings.net work.
Example: layer0.xScale = ease("easeOutCubic",t);
Move a value towards a target value by a given amount.
Example: x = approach(x,10,1);
Returns a random real number between 0 and n.
Example: x = random(10);
Returns a random real number between x and y.
Example: z = random_range(5,10);
Returns a random integer between 0 and n. This includes n if n itself is an integer value.
Example: x = irandom(10);
Returns a random integer between x and y.
Example: z = irandom_range(0,3);
Returns the absolute value of a value.
Example: x = abs(-10);
Returns the given number rounded to the nearest integer.
Example: x = round(3.5);
Returns the given number rounded down to the nearest integer.
Example: x = floor(3.5);
Returns the given number rounded up to the nearest integer.
Example: x = ceil(3.5);
Returns the sign of x.
Example: x = sign(-30);
Returns the decimal part of the given number.
Example: x = frac(3.5);
Returns the square root of x. x cannot be a negative value.
Example: x = sqrt(128);
Returns x*x.
Example: x = sqr(4);
The exponential function.
Example: x = exp(2);
Returns the natural logarithm of the input value.
Example: x = ln(8);
Returns the log base 2 of x, the number 2 must be powered by to equal x.
Example: x = log2(128);
Returns the log base 10 of x.
Example: x = log10(100);
Returns the sine of x (x in radians).
Example: x = sin(1);
Returns the cosine of x (x in radians).
Example: x = cos(1);
Returns the tangent of x (x in radians).
Example: x = tan(1);
Returns the inverse sine of x.
Example: x = arcsin(20);
Returns the inverse cosine of x.
Example: x = arccos(20);
Returns the inverse tangent of x.
Example: x = arctan(20);
Calculates arctan(y/x) and returns an angle in the correct quadrant.
Example: x = arctan2(1,1);
Returns the sine of x, where x is in degrees.
Example: x = dsin(90);
Returns the cosine of x, where x is in degrees.
Example: x = dcos(90);
Returns the tangent of x, where x is in degrees.
Example: x = dtan(90);
Returns the inverse sine of x, where x is in degrees.
Example: x = darcsin(-1);
Returns the inverse cosine of x, where x is in degrees.
Example: x = darccos(-1);
Returns the inverse tangent of x, where x is in degrees.
Example: x = darctan(-1);
Calculates arctan(y/x) and returns an angle in the correct quadrant.
Example: x = darctan2(1,1);
Returns x transformed to radians.
Example: x = degtorad(90);
Returns x transformed to degrees.
Example: x = radtodeg(1);
Returns the given number to the given power; the number x multiplied by itself n number of times.
Example: x = power(2,4);
Returns the log base n of x.
Example: x = logn(5,10);
Returns a value clamped between the specified minimum and maximum.
Example: x = clamp(-5,0,10);
Returns the linear interpolation of two input values by the given amount.
Example: x = lerp(x,mouse_x(),.5);
Returns the difference between two angles.
Example: x = angle_difference(90,180);
Returns the length of a vector comprised of the specified components.
Example: x = point_distance(20,20,50,20);
Returns the direction, in degrees, of a vector comprised.
Example: a = point_direction(x,y,mouse_x(),mouse_y());
Returns the horizontal x-component of the vector determined by the indicated length and direction.
Example: x = lengthdir_x(10,45);
Returns the horizontal y-component of the vector determined by the indicated length and direction.
Example: y = lengthdir_y(10,45);

Returns the color created with the given red, green and blue values.
Example: layer0.flashColor = make_color_rgb(100,200,255);
Returns a colour based on hue, saturation and value.
Example: local col = make_color_hsv(100, 145, 255);
Returns the red component of the given color.
Example: local red = color_get_red(color);
Returns the green component of the given color.
Example: local green = color_get_green(color);
Returns the blue component of the given color.
Example: local blue = color_get_blue(color);
Returns the hue component of the given color.
Example: local hue = color_get_hue(color);
Returns the saturation component of the given color.
Example: local saturation = color_get_saturation(color);
Returns the value component of the given color.
Example: local value = color_get_value(color);
Returns a merge from color_a to color_b by the given amount from 0 to 1.
Example: layer0.flashColor = merge_color(c_blue,c_red,.5);

Returns the number of characters of the given string.
Example: local count = string_length("Hello World");
Returns the number of bytes in a string.
Example: local count = string_byte_length("Hello World");
Returns the character position of an instance of a sub-string within a string, or 0 if it's not found at all..
Example: local pos = string_pos("World","Hello World");
Returns a copy of the string given a starting index and a count amount of characters.
Example: local world = string_copy("Hello World",6,5);
Returns the character of a given string in the given position.
Example: local W = string_char_at("Hello World",7);
Returns a copy of the given string with part of the string being deleted.
Example: local Hello = string_delete("Hello World",5,6);
Returns a copy of a given string with a substring inserted into a chosen position.
Example: local HelloWorld = string_insert(" World","Hello",5);
Returns a copy of a given string in all lowercase letters.
Example: local hello_world = string_lower("HELLO WORLD");
Returns a copy of a given string in all uppercase letters.
Example: local HELLOW_WORLD = string_upper("hello world");
Returns a copy of a given string repeated a given number of times.
Example: local batman = string_repeat("Na",10).." batman!";
Returns a copy of a given string with everything but its letters removed.
Example: local hello = string_letters("h1e2l3l4o5");
Returns a copy of a given string with everything but its numbers removed.
Example: local _123 = string_digits("a1b2c3");
Returns a copy of a given string with everything but its letters and digits removed.
Example: local escaped = string_lettersdigits(password);
Returns a copy of a string with the first instance of a given substring replaced with a new substring.
Example: local hello_world = string_replace("Hello You","You","World");
Returns a copy of a string with all instances of a given substring replaced with a new substring.
Example: local hellow_world = string_replace_all("H$e$l$l$o W$o$r$l$d","$","");
Returns the number of instances of a substring found within a given string.
Example: local hello_es = string_count("hello","hello hello world");
Returns the width of the string in pixels.
Example: local width = string_width("Hello World");
Returns the height of the string in pixels.
Example: local height = string_height("Hellow World");
Returns the maximum width in pixels of a string based on the given separation and line-break width.
Example: local width = string_width_ext("Hellow World",-1,100);
Returns the maximum height in pixels of a string based on the given separation and line-break width.
Example: local height = string_width_ext("Hellow World",-1,100);;

Returns the index of an opened file that allows writing into it.
Example: local file = file_open_write("txt|.txt","example");
Returns the index of an opened file that allows being read.
Example: local file = file_open_read("txt|.txt","example");
Closes an opened file.
Example: file_close(file);
Writes an string to a previously opened file.
Example: file_write_string(file,"Hellow World");
Writes a number to a previously opened file.
Example: file_write_real(file,15);
Writes a linebreak to a previously opened file.
Example: file_writeln(file);
Reads the current line of a previously opened file as a string.
Example: local string = file_read_string(file);
Reads the current line of a previously opened file as a number.
Example: local real = file_read_real(file);
Jumps to the next line on a previously opened, read-only, file.
Example: file_readln(file);

Returns the number of frames that are on queue to be rendered.
Returns -1 if no frames are waiting to be rendered.
Example: draw_text(20,20,tostring(frames_to_render()));

Changes the layer's origin point by the given position.
Example: layer_set_offset(layer0,64,64);
Returns the given layer's width.
Example: layer_get_width(layer0);
Returns the given layer's height.
Example: layer_get_height(layer0);

Gets the current draw colour.
Example: local color = draw_get_color();
Sets the base colour for the draw functions.
Example: draw_set_color(c_white);
This function returns the current value of the draw alpha from 0 to 1.
Example: local alpha = draw_get_alpha();
Sets the alpha for the draw functions.
Example: draw_set_alpha(1);
Clears the entire screen with color.
Example: draw_clear(c_red);
Clears the entire screen with color by the given alpha.
Example: draw_clear_alpha(c_lime,.5);
Draws a point to the screen.
Example: draw_point(64,64);
Draws a line one pixel wide.
Example: draw_line(0,0,10,0);
Draws a line with the given width.
Example: draw_line_width(5,5,10,10,2);
Draws a rectangle to the screen.
Example: draw_rectangle(0,0,64,64,0);
Draws a rectangle with rounded corners of a fixed radius.
Example: draw_roundrect(20,20,50,50,1);
Draws a rectangle with rounded corners of the given radius.
Example: draw_roundrect_ext(50,50,60,60,2,2,0);
Draws a triangle using three defined points.
Example: draw_triangle(50,50,200,50,50,200,0);
Draws a circle to the screen.
Example: draw_circle(layer0.realX,layer0.realY,64,1);
Draws an ellipse to the screen.
Example: draw_ellipse(100,100,300,200,0);
Sets the precision for drawing a circle or ellipse.
Example: draw_set_circle_precision(12);

Aligns any subsequently drawn text horizontally.
Example: draw_set_halign(fa_left);
Aligns any subsequently drawn text vertically.
Example: draw_set_valign(fa_top);
Draws a text to the screen
Example: draw_text(0,0,"Hellow World");
Draws a string at a given position with a specific spacing and within a limited area.
Example: draw_text_ext(100, 50, "Hellow World", 3, 300);
Draws a string with scaling and rotation.
Example: draw_text_transformed(0,0,"Hellow World",2,2,0);
Draws a string with custom spacing and scaling.
Example: draw_text_ext_transformed(0,0,"Hellow World",-1,100,2,2,0);
Draw a string at a given position with a colour gradient.
Example: draw_text_color(64,64,"Hellow World",c_black,c_black,c_white,c_white,1);
Draws a string with custom spacing and colours.
Example: draw_text_ext_color(64,64,"Hello World",-1,100,c_red,c_blue,c_red,c_blue,1);
Draws a string with scaling and colour.
Example: draw_text_transformed_color(20,20,"Hello World",2,2,c_white,c_gray,c_dkgray,c_black,1);

Returns the time in microseconds.
Example: layer0.xSkew = time() * 0.000001;
Returns a value that oscilates between from and to given the duration in seconds.
You can also specify an offset.
Example: layer0.xSkew = wave(-.5,.5,1,0);
Returns a number from 0 to 1 given the render time. This number gets reset after simulating the animation.
Example: layer0.xScale = simulation_time();
Sets the speed multiplier that affects time(),secs() and radsinsecs().
Example: set_speed_multiplier(.5);
Returns the current speed multiplier for time(),secs() and radsinsecs() functions.
Example: local current_multiplier = get_speed_multiplier();
Returns the time of the animation in seconds.
Example: layer0.xScale = secs();
Returns the time of the animation in radians.
Example: layer0.xScale = math.sin(radsinsecs());

Draws a sprite at a given position.
Example: draw_sprite(layer0.sprite_index,0,64,64);
Draws a sprite stretched between four given points and with an alpha blend.
Example: draw_sprite_pos(layer0.sprite_index,0,20,20,40,20,40,40,20,40,1);

Image taken from Game Maker Studio documentation.
Draws a sprite at a given position, with customizable scaling, rotation, blend and alpha.
Example: draw_sprite_ext(layer0.sprite_index,0,64,64,.5,.5,90,c_red,1);
Draws a sprite at a given position, stretched.
Example: draw_sprite_stretched(layer0.sprite_index,0,layer0.realX,layer0.realY,100,100);

Image taken from Game Maker Studio documentation.
Draws a sprite at a given position, stretched, and allows for a custom blend and alpha. This function ignores the sprite's origin.
Example: draw_sprite_stretched_ext(layer0.sprite_index,0,layer0.X,layer0.Y,100,150,c_blue,1);
Draws a sprite at a given position, and tiles it to fill the entire view.
Example: draw_sprite_tiled(layer0.sprite_index,0,layer0.realX,layer0.realY);
Draws a sprite at a given position with scaling, blending and alpha, and tiles it to fill the entire view.
Example: draw_sprite_tiled_ext(layer0.sprite_index,0,layer0.realX,layer0.realY,c_red,1);
Draws part of a sprite at a given position.
Example: draw_sprite_part(layer0.sprite_index,0,0,0,20,20,layer0.realX,layer0.realY);
Draws part of a sprite at a given position with scaling, blending and alpha options.
Example: draw_sprite_part_ext(layer0.sprite_index,0,10,10,20,20,layer0.realX,layer0.realY,2,2,c_red,1);
Draws a part of a given sprite with options for scaling, blending and rotation.
Example: draw_sprite_general(layer0.sprite_index,0,20,20,40,40,layer0.realX,layer0.realY,2,1,90,c_red,c_blue,c_lime,c_black,1);

Randomly returns one of the given arguments.
Example: layer0.X = choose(0,10,20,30);
Returns the value of the given layer's alarm.
Example: local alarm1 = get_alarm(layer0,1);
Sets the value of the given layer's alarm.
Example: set_alarm(layer0,1,10);
Returns the mouse's X position.
Example: layer0.X = mouse_x();
Returns the mouse's Y position.
Example: layer0.Y = mouse_y();
Sets the clipboard text to the given one.
Example: clipboard_set_text("Hello World");



					function update()
					    layer0.xScale = .75 + .25*math.sin(math.cos(radsinsecs()));
					    layer0.yScale = math.cos(math.cos(radsinsecs()));
					end
					

					function update()
					    layer0.flashColor = merge_color(c_red,c_lime,wave(0,1,1,0));
					    layer0.flashTimer = 10;
					    layer0.flashIntensity = wave(0,4.5,0.5,0)
					    layer0.xScale = .75+.25*math.sin(math.sin(radsinsecs()));
					    layer0.yScale = math.cos(math.cos(radsinsecs()));
					    layer0.imageAngle = wave(0,360,2,0);
					end
					

					function update()
					    local t = 1-simulation_time();
					    t = (t*t*t*t);
					    local s = 1+math.sin(math.rad(t*270));
					    layer0.xScale = s;
					    layer0.yScale = s;
					end
					

					t = 0;

					function simulate()
					    t = 0;
					end

					function update()
					    t = t + 0.025;
					    local s = ease("easeOutBounce",t);
					    layer0.xScale = s;
					    layer0.yScale = s;
					end
					

					t = 0;

					function simulate()
					    t = 0;
					end

					function update()
					    t = t + 0.01;
					    local s = ease("easeOutElastic",t);
					    layer0.imageAngle = -20+s*20;
					    layer0.xScale = .5+s*.5;
					    layer0.yScale = .5+s*.5;
					end
					

					function render_start()
						file = file_open_write("json|*.json","");
						file_write_string(file,'{ "frames":[');
						file_writeln(file);
					end

					function render()
						write_frame_info()
					end

					function render_end()
						file_write_string(file,']}');
						file_close(file);
					end

					function write_frame_info()
						frame_info = "";
						file_write_string(file,'    {');
						add_property("x",layer0.X);
						add_property("y",layer0.Y);
						add_property("xscale",layer0.xScale);
						add_property("yscale",layer0.yScale);
						frame_info.sub(1, -2);
						file_write_string(file,frame_info);
						file_write_string(file,'}');
						if(frames_to_render() > 0) then
							file_write_string(file,',');
						end
						file_writeln(file);
					end

					function add_property(name,value)
						frame_info = frame_info..'"'..tostring(name)..'":'..tostring(value)..',';
					end