Script Files

User Guides > ArtRage 4 > Script Files

Script Files

Script Files are a way to record and play back the process of creating a painting so that it can be played back later to reconstruct the painting from a clear canvas, stroke by stroke. Script files are easy to share with other users and can also record annotations, allowing you to make notes while you paint to display during playback for the easy creation of tutorials.

Because Script Files record the process of making each stroke rather than the result they can be played back at different resolutions, allowing you to recreate paintings at different sizes. Advanced users can also edit script files directly via a text editor, changing properties of the painting and the scripting language includes the ability to write C style code functions to create special effects.

Recording Script Files

To record a Script, select ‘Record Script…’ from the File Menu. When you select this item, the Record Script panel appears.

This panel allows you to select what will be included in the Script file when it is recorded.

Including the current painting in your script means that when anyone plays it, the contents of your canvas as they are when you select Record will appear before the script is played.

Turning the ‘Include Current Painting’ option on will cause the script file to be larger, because all painting information (including any layer contents) will be added to the script.

If the canvas is blank, or if the person playing the script does not need the current contents in order for the script to work, do not turn this option on. For example, if you have already painted a face and want to record the process of adding an eye as a tutorial, you might include the current painting so that the face is visible when the script is played. In general, this option should be turned off.

Important: Including the current painting in your script prevents the script being played back at larger size later. Do not turn the option on unless you specifically want paint that is already on the canvas to be included in script playback. If you do need to include the current painting, consider Merging all Layers before you record the Script, this will cut down on the size of the eventual Script File.
Advanced Users: You can write script files manually. For information on how to do this see the Advanced Scripting section later in this manual.

Controlling Recording

While the Script is recording, the Recorder Panel appears. This panel allows you to control the process of recording and add Annotations if you are using ArtRage.


The top line of the Recorder Panel tells you what the Recorder is currently doing. If you Pause recording, the top line will pulse to let you know that nothing is being recorded.

The buttons on the second line of the panel allow you to Pause or Resume recording, or Stop recording completely. When you Stop recording you will be prompted for information before the Script is saved.

If recording is paused, nothing you do in ArtRage will be recorded. This means the Script may not play back correctly if you paint while paused.

The buttons below allow you to add Annotations to the Script. Annotations are used to provide information to the person who is playing the Script. More information is available regarding Annotations later in the manual.

Pausing and Idle Time

If you stop painting at any point during recording and do nothing in ArtRage, this is recorded as idle time. When a user plays back your Script they will be given the option to accelerate playback, which removes all idle time from playback, otherwise the script will pause during playback until the idle time expires. Users are given the option to skip idle time manually if it occurs during playback.

If you are going to be away for an extended period during recording, consider pressing Pause on the Recorder Panel. While recording is paused idle time is not recorded so there will be no pause in the action during playback.

Saving Your Painting While Recording

If you save your painting while recording, the script is saved with it. If you then quit, recording will start again when you reload the painting later to continue working on it. This will continue until you specifically end recording.

Ending Recording

When you are read to end recording, click the Stop button on the Recorder Panel. When you click this button, the Save Script Panel appears. This panel allows you to enter information for your script and save it, or cancel and discard the recoded script.

If you Cancel in this panel, you will be given the opportunity to continue recording from where you left off, or to discard the script entirely.

The information requested in this panel is optional, you do not need to enter any information here. ArtRage will not display empty information items, so if your Script has no preview, no preview area will be displayed when it is played.


To set a Preview either click in the Preview Image section to select an image to use, or drag the image from your computer on to that section. The image needn’t be 400 x 80 pixels but it will be scaled to that size when it is loaded so it may look unusual if it has different dimensions.

Click in the Script Name, Script Author, and Script Description sections to set those values. The name of your Script does not need to be unique.

When you are done editing information, click OK and you will be asked to save the Script to a ‘.arscript’ file. That file is the file that will be played back in the future.

Script Annotations

Annotations allow you to present additional information to someone during Script playback. While the script is being recorded you can add three types of Annotation depending on the kind of information you want to present: Notes, Tips, and Spotlights.


Notes are messages that appear and interrupt the flow of the script. When the Note appears, playback is paused until the user clicks Continue. Use Notes when you have complex information that requires reading and understanding before the script continues.


Tips look like Notes but the script continues to play while the Tip is visible and the Tip vanishes when the original Author wants it to vanish. Use Tips when you want to illustrate something that is currently happening and doesn’t require a lot of explanation.


Spotlights appear on the canvas as a dark or light blurred patch with a hole in the centre. They are used to highlight important areas of painting while you work. Spotlights remain on the canvas until the Author dismisses them. There can only be one Spotlight at a time.

Spotlights can coexist with Notes and Tips, so you can add a Spotlight then add a Note to explain what it is highlighting. Use them to focus the user’s attention on an area of the canvas during script playback.

Adding Notes and Tips

To add a Note or a Tip, click the appropriate button on the Recorder Panel. When you do this, a Note Editor appears:


Enter your text in the space provided in the bubble then click the tick to add the Note or Tip.

The bubble will automatically adjust its height fit its contents as you type.

The green handles on either side of the bubble are used to change its width. The bubble will resize its height to fit its contents as you do this.

The target button indicates where the ‘tail’ of the bubble will sit when the Note or Tip appears. You can move the tail by clicking and dragging on the target. It can go anywhere inside the dark border of the Note Editor.

You can click and drag in the dark border to move the Note Editor. When the Note or Tip is displayed, the dark border will not be visible, it is only displayed here to contain editing controls.

If you are creating a Note, the ‘Continue’ text will be visible in the bubble. This is to show you how the final bubble will look when it is displayed.

Dismissing Tips

Tips remain on the canvas during recording until you want to dismiss them. For example, you could create a Tip that says ‘Part 1: The Eyes’ and leave it on the canvas until you have finished drawing the eyes for a portrait, then dismiss the tip when you go on to the next task. As an author, you add the Tip when you want it to appear, then as you are recording you click it to close it.


When you add a Tip to the canvas while recording, it looks like this. Click the tip when you want to remove it. When the script is played back, this is the point at which it will vanish from the canvas.

When playback ends, any open Tips are automatically closed. You can have as many open as you like during playback.

Adding Spotlights

To add a Spotlight click the Add Spotlight button on the Recorder Panel. When you do this, all other panels fade out and the Spotlight Editor appears.


The target button in the centre can be clicked and dragged to move the spotlight. This represents the centre of your point of interest.

The radius button that sits on the edge of the Spotlight can be dragged to change its size.

The Menu Button allows you to select whether this is a Dark or Light Spotlight. Use Dark Spotlights (the default) on light canvases, and use Light Spotlights on Dark canvases.

When you have positioned and sized the Spotlight, click the tick button to okay its addition to the Script.

If you move a Spotlight so that the OK and Cancel buttons are off the screen, they will shuffle to the other edge to make sure they are visible. If you lose them for any reason you can press Enter to okay the Spotlight, or Escape to cancel it.

Playing Script Files

To play a Script select ‘Play Script…’ from the File Menu. When you select this option you will be prompted to save your current Painting if there are unsaved changes, then asked to select a ‘.arscript’ file to play. Once you have selected a file the Play Script Panel appears.


This panel contains any information that was saved with the Script file, including its title, its author, a description and a preview.

It also allows you to make two choices about how the Script will be played including speed and whether the result will be the same size as the original painting.

If you choose Accelerate Playback, any idle time that was recoded in to the script by the author will be ignored. This speeds up the process of playback. If you do not turn this option on you will be given the option to manually skip any idle time as it occurs during playback.

Accelerating playback also accelerates the paint strokes.

Playing the Script at its original size causes a new canvas to be created at the indicated size when you click Play. If you would prefer the Script to play back at a different size, turn off the Play at Original Size option and enter the size you would like to use using the Screen Size or Print Size controls. Click Play when you are ready to start the Script playing.

Selecting Different Sizes

If you opt to play back the script at a custom size you are provided with full control over the sizing of the new file as per the new file dialog. This allows you to set the size in pixels or screen units.

Because the Script records the process of painting rather than the resulting image, playing Scripts back at different sizes allows you to recreate them as if they had originally been painted at that size. The result is a higher quality way to scale images.

Normal image scaling takes the resulting picture and stretches it, which reduces the quality of the paint strokes. Script scaling using the Play Script Panel re-paints the script at a different scale, so each paint stroke has the same quality as one painted by hand.


While ArtRage scales the path of the strokes and the properties of the brush as best it can, you may find that the results of a Script played back at larger scale do not look identical to the original result. In general however, the result should be very similar.

In this example the paint stroke was created at 200 x 200 pixels in size and recorded in a script. The two examples below show the difference between scaling the image up 200% and playing back the script at 200%. The scaled image is fuzzier and lower quality, while the Script image is crisp as if the stroke had been originally painted at that size.


Scaled to 200%


Script Played at 200%

Controlling Playback

While a Script is playing the Playback Controls panel appears. This panel contains controls that you can use during playback. While a Script is playing you cannot interact with any other control in ArtRage.


The top bar indicates what the Player is currently doing. If you have chosen not to accelerate playback and the script contains idle time (time where the author was not doing anything during recording) the top bar will update to indicate how long until the idle time ends, and a ‘Skip’ button that allows you to skip past the idle time.

Click the Pause button to pause playback, or continue if it has been paused.

The percentage indicator tells you how far through the Script you are. Note that this is not based on time but on the number of events that were recorded.

Click the Stop button to stop playback. When you do this, the Playback Controls Panel vanishes and your canvas is left in the state it was in at that point in the script.

If you play a Script through to the end, the Playback Controls panel will vanish of its own accord.

Notes, Tips and Spotlights

Notes and Tips are messages left by the Script Author to help explain what is happening.


If a bubble appears that has a ‘Continue’ button at the bottom, the Script will pause until you click inside the bubble. This is a ‘Note’.


If a bubble appears that does not have a ‘Continue’ button at the bottom, the Script will continue to play. You cannot dismiss these manually, they will vanish when the Script Author wants it to. This is a ‘Tip’.


If a dark blurred area with a hole in the middle appears, the Script will continue to play underneath it. This is a Spotlight and it will vanish when the Script Author wants it to.

Spotlights are used to draw your attention to important parts of the canvas while the Script is playing.

Advanced Scripting

ArtRage Scripts are text files that store data in a human readable format. This allows you to edit the contents of the Script directly and change its properties, or create entirely new scripts from scratch using the ArtRage Scripting Language. The Scripting Language allows you to instruct the application to do anything that can be done by a user, and also includes mathematical and string operators, and the ability to script functions that can be called as the Script is played.

The Scripting Language is not covered in this manual, but full details can be found in the ArtRage Scripting Guide [PDF].

Scripts that are created manually should be saved with the ‘.arscript’ suffix and can be loaded in to the application via the standard Play Script menu option.