Getting Started with Light.VN Commands pt. 1
Archived from Ko-fi, without images
Other Light.VN posts
A translation and commentary of the official wiki page on commands. This one should be suitable for a beginner, but it will make much more sense if you read it after trying the tutorial game and peek into the script file.
This is not a 1:1 translation and I have rearranged some concepts in ways I personally find more natural in my own learning.
Overview
Command is the main structure of a Light.VN script. Any script can be broken down into sequences of commands, and most of these commands follow a predictable template. While the most basic of these commands (those pertaining asset declaration) are available from the lefthand panel of the editor, learning how to read them properly will ease your debugging attempt and speed up development.
You can recognize commands as colored keywords, while the part of your script treated as text is colored blue. These are usually preceded by a tilde "~".
- When attempting to invoke a command in the middle of a text block, you have to write the tilde "~" so the editor can distinguish it from raw text (if your command is colored blue, the editor thinks it is text and will render it as is. You might need a preceding "~" for it to work correctly). However, outside of it, you can choose to use the tilde or not. Pick one style and be consistent.
~ Here's one of the coolest things Light.VN editor provides: if you click on any command, the explanation pane below the preview pane will show you what that command does and what parameter it will accept. You can also browse commands from this pane. This means you can read the documentation without leaving the editor. It lacks easy searchability, but the commands are grouped by categories so if you spend time familiarizing yourself with the groupings you will be rewarded in the future.
Command types
- Object Declaration Command
cg, bg, soundEffect, bgm, button... these commands create an object with specific names and parameters to be shown and manipulated in other commands. It typically will look for the asset starting from the matching asset folder (e.g cg and bg will look under Images/, soundEffect will look under SFX/). If your assets are arranged differently, you may have to supply full paths from Data/. Any path from Data should be preceded by a slash) With the exception of soundEffect, all objects declared should be named.
- Parameter Setting Command
Always requires a target! These commands take on one or more already-existing object(s) and set or remove their parameters.
- Effect Command
What we usually know as ATL in Ren'py. These commands always require a target, to which certain visual manipulations will be performed. For example, move, rotate, ... which will take on absolute values.
Most of these commands have alternate versions, such as move2, rotate2, ... where you can supply relative values (to their current values) such as +10, -50...
For effect commands that take durations, by default, the operations will be carried out in parallel. You can add a period (.) at the beginning of such command to indicate that you want the game to wait until that command to finish before processing the next line. Such command is called synchronized commands.
Be careful! You may accidentally freeze your editor if you carelessly place a period in front of a looping command, because then the system never knows when to stop. Ask how I know.
You cannot apply synchronized commands directly on key triggers and timed objects, but it will work if you apply the command indirectly by setting scripts.
- System Command
Commands setting particular aspects/behaviors of the game/engine. These usually don't need a target and can simply require values, such as textColour.
- Camera Handling Command
Commands related to camera operation, such as move, rotate, ... Note the difference between moving the camera itself and moving individual objects. The camera can be manipulated with the target name vn_sys_camera. By manipulating the camera, you can make it look like all objects move without changing their actual positions, allowing for visual flairs such as earthquakes or certain cinematic effects.
Command Structure
A command typically has this structure
[keyword name parameter1 parameter2 parameter3 ...]
Use space to separate the parameters, and upon completion, if you write the line correctly, your command will be applied. Let's break the parts down one by one.
Command keywords!
keyword - how you tell the editor you want to call a particular command. This is the entry you will see in the wiki and the explanation pane, such as wait, jump, image, ... keywords are grouped into five broad categories (object declaration command, parameter setting command, effect command, system command, and camera handling command).
name - this is the name you give to the object created or referred by the command. Always make sure you never have two different objects with the same name. If you have the command "movex title_bg 10" you tell it to move the object named "title_bg" 10 pixels horizontally. No other object will be moved. You can provide multiple targets to a command by separating them with a comma and a space, like "movex title_bg, logo, subtitle 10". The space between entries is not optional. If you do not provide a target, these kinds of commands will not be executed. Not every type of commands need an object. There are setting/system commands that only require values, such as textColour. If you have overlaps of names, the name will be used for the latest/newest object. Object name cannot begin with numbers. You cannot use mathematical operators as part of your name (as this will likely interfere with the regex function). You can have space in your object name, but it must be enclosed as a string such as "my object name". Light.VN leverages regex to refer to multiple objects at once, so if you use a particular naming scheme like title_bg, title_subtitle, title_logo, title_character, you can make them fade in and out all at once by targeting title_.*
~ Some commands allow you to use its name as a target. For example, you can have multiple objects bound to a single button command, and applying the command "fadein button" will affect all the constituent components.
~ You can target all elements on display at once by using "all". "fadeOut all" will fade every single item on the screen, including those with 0 alpha.
parameters - for asset-related commands, the parameters are usually filepath, coordinates, rate of change, and duration of change.
bg0 gameBG_bg0 Images/Game_BG.png 0 0 98 on_camera
.fadein gameBG_bg0 200
wait 800
In this example, the command "bg0" (background declaration command) has the following parameters:
name: gameBG_bg0
**path: Images/Game_BG.png
coordinates: x=0, y=0, layer=98
extra argument: on_camera (meaning the picture will stay fixed on screen no matter how we handle the camera later)
Explanation Pane
Click on a command to see what parameters it can accept in the explanation window!
The original wiki page has a section on acceleration, camera handling, screenspaces, and coordinates. I have decided to spin that off to a separate post, as I don't think they are very relevant crammed in the same section.
Hopefully this will be of some help to you.