Finished general scripting page

- TODO: child scripts page
stipple-effect · Dec 30, 2024 · 23b31e2 · 23b31e2
1 parent 36c3423
commit 23b31e2
Show file tree

Hide file tree

Showing 6 changed files with 37 additions and 61 deletions.
diff --git a/child-scripts.md b/child-scripts.md
@@ -2,4 +2,8 @@
 
 [`< Scripting`](scripting.md)
 
-<!-- TODO -->
+<!-- TODO -->
+
+[Child scripts](./child-scripts.md) are merely scripts that are run from within another script. Child scripts can have any type signature, but will trigger a runtime error if they are passed arguments that do not match the types of the parameters of their [header function](#syntax).
+
+You may run scripts from within any script, but it is recommended *NOT to run child scripts from within preview or color scripts* for the sake of performance. Also in the interest of performance, it is optimal to declare any child scripts used in a script as `final` (also `~`) `script` variables outside any loops. This way, the child script will only be loaded once per its parent script's execution.
diff --git a/color-scripts.md b/color-scripts.md
@@ -2,7 +2,7 @@
 
 [`< Scripting`](scripting.md)
 
-**Color scripts** are used to define the behaviour of the [script brush](./script-brush.md) ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/script_brush.png) and the [run a color script](./color-actions.md#run-a-color-script) ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/color_script.png) color action. They describe a **color to color transformation**.
+**Color scripts** are used to define the behaviour of the [script brush](./script-brush.md) ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/script_brush.png) tool and the ["run a color script"](./color-actions.md#run-a-color-script) ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/color_script.png) color action. They describe a **color to color transformation**.
 
 **Note:**
 

diff --git a/frame.md b/frame.md
@@ -36,39 +36,39 @@ These playback modes are merely internal. When projects are [exported](./save.md
 
 ### ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/new_frame.png) Add new frame
 
-[*API function*](../se-api/project.md#add_frame)
+[*API function*](../api/project.md#add_frame)
 
 **Shortcut:** <kbd>Ctrl</kbd> + <kbd>F</kbd>
 
 Adds a new frame to the project directly after the current active frame. The new frame becomes the new active frame.
 
 ### ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/duplicate_frame.png) Duplicate frame
 
-[*API function*](../se-api/project.md#duplicate_frame)
+[*API function*](../api/project.md#duplicate_frame)
 
 **Shortcut:** <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>F</kbd>
 
 Duplicates the current active frame of project and inserts the duplicate directly after the initial frame. The duplicate frame becomes the new active frame.
 
 ### ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/remove_frame.png) Remove frame
 
-[*API function*](../se-api/project.md#remove_frame)
+[*API function*](../api/project.md#remove_frame)
 
 **Shortcut:** <kbd>Ctrl</kbd> + <kbd>Backspace</kbd>
 
 Removes the current active frame of the project. If the frame to be removed is the first frame, the active frame becomes the new first frame after the removal. Otherwise, the new active frame is the frame that preceded the frame that was removed.
 
 ### ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/move_frame_back.png) Move frame back
 
-[*API function*](../se-api/project.md#move_frame_back)
+[*API function*](../api/project.md#move_frame_back)
 
 **Shortcut:** <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + *Left Arrow Key*
 
 Swaps the active frame of the project with the preceding frame.
 
 ### ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/move_frame_forward.png) Move frame forward
 
-[*API function*](../se-api/project.md#move_frame_forward)
+[*API function*](../api/project.md#move_frame_forward)
 
 **Shortcut:** <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + *Right Arrow Key*
 

diff --git a/preview-scripts.md b/preview-scripts.md
@@ -150,7 +150,7 @@ These are then superimposed on copies of `anim_head`, sliced into 8 directions i
 
 This script utilizes the following API function:
 
-* [`$Graphics.uv_mapping(image texture, image map, image animation) -> image`](../se-api/graphics.md#uv_mapping)
+* [`$Graphics.uv_mapping(image texture, image map, image animation) -> image`](../api/graphics.md#uv_mapping)
 
 This script utilizes the following functions from the *DeltaScript* base language [standard library](https://github.com/jbunke/deltascript): <!-- TODO - GitHub link to SL -->
 

diff --git a/preview-window.md b/preview-window.md
@@ -21,7 +21,7 @@ The preview window is rendered on top of all other UI elements and can be **free
 
 **Note:**
 
-There is an option in the visual settings ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/settings.png) to open the preview window in a separate UI window from the main program.
+There is an option in the visual settings to open the preview window in a separate UI window from the main program. However, even with this option turned on, **the preview window will always be embedded in the main program window if the program is maximized**.
 
 ### Playback controls
 

diff --git a/scripting.md b/scripting.md
@@ -2,56 +2,42 @@
 
 [`< Overview`](./README.md)
 
-<!-- What? -->
+*Stipple Effect* lets users write scripts for a range of applications. A **script** is a short series of instructions for the program to execute.
 
-## Scripting basics
+## DeltaScript
 
-Stipple Effect scripts fall into the following categories:
+*Stipple Effect* scripts are written in a scripting language called [*DeltaScript*](https://github.com/jbunke/deltascript), which was designed by the developer of the program. *DeltaScript* is described as a **lightweight scripting language skeleton**. This means that the *DeltaScript* base language is easy to learn, with only essential functions in its standard library. <!-- TODO - standard library link -->
 
-* [Automation scripts](#automation-scripts)
-* [Preview scripts](#preview-scripts)
-* [Color scripts](#color-scripts)
-* [Child scripts](#child-scripts)
+The language was also designed to be **powerful**, **expressive**, and **concise**. The syntax is concise and devoid of [boilerplate](https://en.wikipedia.org/wiki/Boilerplate_code), and has many shorthands to make scripts shorter without sacrificing readability. It should also be familiar to users with prior programming experience, as the **syntax is similar to other [C-family languages](https://en.wikipedia.org/wiki/List_of_C-family_programming_languages) like C++, Java, JavaScript, and Go**.
 
-### Automation scripts
+**Do not be discouraged if you have little to no programming experience, or if you are hesitant about learning a new language.** There are plenty of resources to familiarize yourself with scripting in _Stipple Effect_, including:
 
-[Automation scripts](automation-scripts.md) are scripts that run a series of program actions automatically. For example, a script can be written that reverses the frames in a project. The full list of Stipple Effect program actions that can be executed via script are outlined in the [scripting API](../api/).
+* [Script examples with explanations](https://github.com/jbunke/se-script-examples)
+* [DeltaScript language specification](https://github.com/jbunke/deltascript/blob/master/docs/lang-spec.md)
+* [*Stipple Effect* YouTube playlist (w/ tutorials)](https://www.youtube.com/playlist?list=PLy71S74rTLnPEwYYtAXvh2er8QBvWIwRL)
 
-Type signature for automation scripts: `()` - (no parameters and void return)
+## API
 
-### Preview scripts
+*DeltaScript* is designed to be extended for the needs of the individual applications that utilize it. As the base language is quite bare, most of the powerful scripting functionality for *Stipple Effect* is defined in the **scripting API** - *Stipple Effect*'s extension of *DeltaScript*. You can read the API specification [here](../api/).
 
-[Preview scripts](preview-scripts.md) allow for creation of complex custom previews by transforming the flattened contents of the project that acts as input into original output. Since preview scripts are essentially a __*mapping*__, the contents of the preview window will change dynamically as the project that defines its input is modified, without having to reload the script.
+## Types of scripts
 
-Valid type signatures for preview scripts:
-* `(image -> image)`
-* `(image[] -> image)`
-* `(image[] -> image[])`
-* `(image -> image[])` - (only valid for projects with a single frame)
+Scripts in *Stipple Effect* scripts fall into the following categories:
 
-### Color scripts
+* [Automation scripts](./automation-scripts.md) - automate tasks and execute actions programmatically
+* [Preview scripts](./preview-scripts.md) - transform the contents of the [project](./project.md) that are displayed in the [preview window](./preview-window.md)
+* [Color scripts](./color-scripts.md) - color to color transformations for the [script brush](./script-brush.md) ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/script_brush.png) tool and the ["run a color script"](./color-actions.md#run-a-color-script) ![](https://raw.githubusercontent.com/jbunke/stipple-effect/master/res/icons/color_script.png) color action
+* [Child scripts](./child-scripts.md) - catch-all term for scripts executed from within other scripts
 
-[Color scripts](./color-scripts.md) transform an input color into an output color. They can be run independently and applied to a certain [scope](./scope.md) of the active project, or they can be used to power the [Script Brush](./scripting-brush).
+## Getting Started
 
-Type signature for color scripts: `(color -> color)`
+### Script files and text editor
 
-### Child scripts
+Script files use the file extension `.ses`. They can be written in the text editor of your choosing. However, **[Visual Studio Code](https://code.visualstudio.com/) (VS Code) is recommended** because of the [*DeltaScript for Stipple Effect* syntax highlighting extension](https://marketplace.visualstudio.com/items?itemName=jordanbunke.deltascript-for-stipple-effect) that is distributed on the VS Code Marketplace.
 
-[Child scripts](./child-scripts.md) are merely scripts that are run from within another script. Child scripts can have any type signature, but will trigger a runtime error if they are passed arguments that do not match the types of the parameters of their [header function](#syntax).
+### Script structure
 
-You may run scripts from within any script, but it is recommended *NOT to run child scripts from within preview or color scripts* for the sake of performance. Also in the interest of performance, it is optimal to declare any child scripts used in a script as `final` (also `~`) `script` variables outside any loops. This way, the child script will only be loaded once per its parent script's execution.
-
-<!-- How? -->
-
-## Getting started
-
-Stipple Effect scripts are written in an extension dialect of [DeltaScript](https://github.com/jbunke/deltascript) designed specifically for the program. DeltaScript is a lightweight, skeletal scripting language that I designed to be extended for the easy design of [domain-specific languages](https://en.wikipedia.org/wiki/Domain-specific_language) interpreted to Java. It has a very simple syntax and will feel familiar to anyone with programming experience in languages such as C, C++, C#, Java and JavaScript.
-
-Script files can be written in the text editor of your choosing and use the file extension `.ses`. However, `VS Code` is recommended, as the official syntax highlighting extension for Stipple Effect scripting is only available for VS Code.
-
-### Syntax
-
-Scripts consist of a nameless header function optionally followed by **named helper functions**. The type signature of the script is the type signature of its header function. Functions can optionally accept parameters and return a value of a specified return type, **though neither are required**.
+Scripts consist of a nameless header function, optionally followed by **named helper functions**. The type signature of the script is the type signature of its header function. Functions can optionally accept parameters and return a value of a specified return type, **though neither are required**.
 
 ```js
 // header function - this is the entry point of the script's execution
@@ -73,28 +59,14 @@ random_letter(-> char) {
     ~ int MIN = (int) 'a';
     ~ int MAX_EX = ((int) 'z') + 1;
 
-    // "rand" is a native function defined by DeltaScript
+    // "rand" is a function defined by the DeltaScript standard library
     return (char) rand(MIN, MAX_EX);
 }
 ```
 
-A full breakdown of the syntax and semantics of DeltaScript can be found in the [language specification](https://github.com/jbunke/deltascript/blob/master/docs/lang-spec.md).
-
-### Example
-
-To get a feel of what DeltaScript looks like, here is an example of a preview script:
-
-<!-- TODO - replace asset with valid DeltaScript code -->
-![Script example](./assets/code-example.png)
-
-When the script above is applied to the project on the left, it produces the preview to the right:
-
-| Input | Output |
-| :---: | :----: |
-| ![Input](./assets/running.gif) | ![Output](./assets/running-channels.gif) |
-| ![Input](./assets/bouncing-ball.gif) | ![Output](./assets/bouncing-ball-channels.gif) |
+A full breakdown of the syntax and semantics of *DeltaScript* can be found in the [language specification](https://github.com/jbunke/deltascript/blob/master/docs/lang-spec.md).
 
-___
+---
 
 **SEE ALSO**