VNgen Reference Guide

  1. Introduction
  2. Buy Now
  3. Download PDF
  4. Changelog
    1. Compatibility Notes
    2. Feature Comparison
  5. Getting Started
    1. Setup & Installation
      1. Additional HTML5 Setup
      2. Additional Language Setup
    2. Intro to Q-script
    3. Your First Visual Novel
      1. Entities & Action Types
      2. A Simple Dialog
      3. A Simple Choice
      4. A Simple Scene
      5. A Simple Script
  6. Reference Guide
    1. Debug Functions
      1. Intro to QCMD
      2. Included Commands
      3. show_debug_vngen
    2. Macros & Keywords
    3. Animations
      1. Creating Custom Animations
      2. Included Animations
      3. deform
      4. keyframe
    4. Effects
      1. Creating Custom Effects
      2. Included Effects
      3. effect
    5. Shaders
      1. Included Shaders
    6. Engine Functions
      1. sys_config
      2. sys_action_init
      3. sys_action_skip
      4. sys_action_term
      5. sys_anim_init
      6. sys_anim_perform
      7. sys_anim_term
      8. sys_anim_speech
      9. sys_cmd_init
      10. sys_cmd_add
      11. sys_cmd_perform
      12. sys_cmd_draw
      13. sys_toggle_cmd
      14. sys_deform_init
      15. sys_deform_perform
      16. sys_deform_draw
      17. sys_deform_term
      18. sys_effect_init
      19. sys_effect_perform
      20. sys_effect_term
      21. sys_event_skip
      22. sys_read_skip
      23. sys_grid_delete
      24. sys_grid_last
      25. sys_layer_set_target
      26. sys_layer_draw_scene
      27. sys_layer_draw_char
      28. sys_layer_draw_emote
      29. sys_layer_draw_perspective
      30. sys_layer_draw_effect
      31. sys_layer_draw_textbox
      32. sys_layer_draw_text
      33. sys_layer_draw_label
      34. sys_layer_draw_prompt
      35. sys_layer_draw_button
      36. sys_layer_draw_option
      37. sys_layer_reset_target
      38. sys_layer_log_set_target
      39. sys_layer_draw_log
      40. sys_layer_draw_log_button
      41. sys_layer_log_reset_target
      42. sys_log_init
      43. sys_log_perform
      44. sys_log_get_style
      45. sys_log_get_xoffset
      46. sys_mouse_hover
      47. sys_option_init
      48. sys_orig_init
      49. sys_queue_enqueue
      50. sys_queue_submit
      51. sys_queue_destroy
      52. sys_queue_empty
      53. sys_scale_init
      54. sys_shader_init
      55. sys_shader_perform
      56. sys_shader_set_sampler
      57. sys_text_init
      58. sys_text_perform
      59. sys_text_get_label
      60. sys_text_get_xoffset
      61. sys_text_style_init
      62. sys_trans_init
      63. sys_trans_perform
      64. sys_vox_add
    7. Global Functions
      1. array_create_2d
      2. interp
      3. is_even
      4. is_odd
      5. make_color_hex_to_rgb
      6. make_color_rgb_to_hex
      7. mouse_region
      8. mouse_region_gui
      9. shader_exists
      10. vngen_continue
      11. vngen_count
      12. vngen_exists
      13. vngen_goto
      14. vngen_goto_unread
      15. vngen_instance_change
      16. vngen_room_goto
      17. vngen_set_cursor
      18. vngen_set_halign
      19. vngen_set_lineheight
      20. vngen_set_speed
      21. vngen_set_vol_music
      22. vngen_set_vol_sound
      23. vngen_set_vol_voice
      24. vngen_set_vol_vox
      25. vngen_set_renderlevel
      26. vngen_set_scale
      27. vngen_set_shader_float
      28. vngen_set_shader_matrix
      29. vngen_set_shader_sampler
      30. vngen_toggle_auto
      31. vngen_toggle_pause
      32. vngen_toggle_visible
    8. File Functions
      1. vngen_file_save
      2. vngen_file_load
      3. vngen_file_delete
    9. Language Functions
      1. vngen_set_lang
      2. vngen_get_lang
    10. Property Functions
      1. vngen_get_prop
      2. vngen_set_prop
      3. vngen_get_index
      4. vngen_get_structure
      5. vngen_get_width
      6. vngen_get_height
      7. vngen_get_x
      8. vngen_get_y
      9. vngen_get_xscale
      10. vngen_get_yscale
      11. vngen_get_rot
    11. Backlog Functions
      1. Buttons
        1. vngen_log_button_create
        2. vngen_log_button_create_ext
        3. vngen_log_button_create_transformed
        4. vngen_log_button_create_ext_transformed
        5. vngen_log_button_destroy
        6. vngen_log_button_clear
        7. vngen_get_log_button
        8. vngen_log_button_nav
        9. vngen_log_button_select
      2. Input
        1. vngen_log_nav
        2. vngen_log_nav_touch
        3. vngen_log_play_audio
        4. vngen_toggle_log
      3. vngen_log_init
      4. vngen_log_add
      5. vngen_log_draw
      6. vngen_log_clear
      7. vngen_log_count
      8. vngen_log_get_index
    12. Object Functions
      1. vngen_object_init
      2. vngen_object_draw
      3. vngen_object_clear
    13. Events
      1. vngen_event_set_target
      2. vngen_event
      3. vngen_event_pause
      4. vngen_event_reset_target
      5. vngen_event_count
      6. vngen_event_get_index
      7. vngen_event_get_label
    14. Actions
    15. Perspective Actions
      1. vngen_perspective_modify_pos
      2. vngen_perspective_modify_direct
      3. vngen_perspective_replace
      4. vngen_perspective_anim_start
      5. vngen_perspective_anim_stop
      6. vngen_perspective_shader_start
      7. vngen_perspective_shader_stop
    16. Scene Actions
      1. vngen_scene_create
      2. vngen_scene_create_ext
      3. vngen_scene_modify_style
      4. vngen_scene_modify_pos
      5. vngen_scene_modify_ext
      6. vngen_scene_modify_direct
      7. vngen_scene_replace
      8. vngen_scene_replace_ext
      9. vngen_scene_destroy
      10. vngen_scene_anim_start
      11. vngen_scene_anim_stop
      12. vngen_scene_deform_start
      13. vngen_scene_deform_stop
      14. vngen_scene_shader_start
      15. vngen_scene_shader_stop
    17. Character Actions
      1. vngen_char_create
      2. vngen_char_create_ext
      3. vngen_char_modify_style
      4. vngen_char_modify_pos
      5. vngen_char_modify_ext
      6. vngen_char_modify_direct
      7. vngen_char_replace
      8. vngen_char_replace_ext
      9. vngen_char_destroy
      10. vngen_char_anim_start
      11. vngen_char_anim_stop
      12. vngen_char_deform_start
      13. vngen_char_deform_stop
      14. vngen_char_shader_start
      15. vngen_char_shader_stop
    18. Character Attachment Actions
      1. vngen_attach_create
      2. vngen_attach_create_ext
      3. vngen_attach_modify_style
      4. vngen_attach_modify_pos
      5. vngen_attach_modify_ext
      6. vngen_attach_modify_direct
      7. vngen_attach_replace
      8. vngen_attach_replace_ext
      9. vngen_attach_destroy
      10. vngen_attach_anim_start
      11. vngen_attach_anim_stop
      12. vngen_attach_deform_start
      13. vngen_attach_deform_stop
      14. vngen_attach_shader_start
      15. vngen_attach_shader_stop
    19. Emote Actions
      1. vngen_emote_create
      2. vngen_emote_create_ext
    20. Effect Actions
      1. vngen_effect_start
      2. vngen_effect_stop
    21. Textbox Actions
      1. vngen_textbox_create
      2. vngen_textbox_create_ext
      3. vngen_textbox_modify_style
      4. vngen_textbox_modify_pos
      5. vngen_textbox_modify_ext
      6. vngen_textbox_modify_direct
      7. vngen_textbox_replace
      8. vngen_textbox_replace_ext
      9. vngen_textbox_destroy
      10. vngen_textbox_anim_start
      11. vngen_textbox_anim_stop
      12. vngen_textbox_deform_start
      13. vngen_textbox_deform_stop
      14. vngen_textbox_shader_start
      15. vngen_textbox_shader_stop
    22. Text Actions
      1. Inline Markup
      2. vngen_text_create
      3. vngen_text_create_ext
      4. vngen_text_modify_style
      5. vngen_text_modify_pos
      6. vngen_text_modify_ext
      7. vngen_text_modify_direct
      8. vngen_text_replace
      9. vngen_text_replace_ext
      10. vngen_text_destroy
      11. vngen_text_anim_start
      12. vngen_text_anim_stop
      13. vngen_text_deform_start
      14. vngen_text_deform_stop
      15. vngen_text_shader_start
      16. vngen_text_shader_stop
    23. Label Actions
      1. vngen_label_create
      2. vngen_label_create_ext
      3. vngen_label_modify_style
      4. vngen_label_modify_pos
      5. vngen_label_modify_ext
      6. vngen_label_modify_direct
      7. vngen_label_replace
      8. vngen_label_replace_ext
      9. vngen_label_destroy
      10. vngen_label_anim_start
      11. vngen_label_anim_stop
      12. vngen_label_deform_start
      13. vngen_label_deform_stop
      14. vngen_label_shader_start
      15. vngen_label_shader_stop
    24. Prompt Actions
      1. vngen_prompt_create
      2. vngen_prompt_create_ext
      3. vngen_prompt_modify_style
      4. vngen_prompt_modify_pos
      5. vngen_prompt_modify_ext
      6. vngen_prompt_modify_direct
      7. vngen_prompt_replace
      8. vngen_prompt_replace_ext
      9. vngen_prompt_destroy
      10. vngen_prompt_anim_start
      11. vngen_prompt_anim_stop
      12. vngen_prompt_deform_start
      13. vngen_prompt_deform_stop
      14. vngen_prompt_shader_start
      15. vngen_prompt_shader_stop
    25. Button Actions
      1. vngen_button_create
      2. vngen_button_create_ext
      3. vngen_button_create_transformed
      4. vngen_button_create_ext_transformed
      5. vngen_button_destroy
      6. vngen_button_clear
      7. vngen_get_button
      8. vngen_button_nav
      9. vngen_button_select
    26. Option Actions
      1. vngen_option
      2. vngen_option_create
      3. vngen_option_create_ext
      4. vngen_option_create_transformed
      5. vngen_option_create_ext_transformed
      6. vngen_option_clear
      7. vngen_get_option
      8. vngen_option_nav
      9. vngen_option_select
    27. Audio Actions
      1. vngen_audio_play_sound
      2. vngen_audio_play_music
      3. vngen_audio_play_voice
      4. vngen_audio_modify
      5. vngen_audio_replace
      6. vngen_audio_pause
      7. vngen_audio_resume
      8. vngen_audio_stop
      9. vngen_vox_play
      10. vngen_vox_modify
      11. vngen_vox_replace
      12. vngen_vox_add
      13. vngen_vox_remove
      14. vngen_vox_pause
      15. vngen_vox_resume
      16. vngen_vox_stop
    28. Code Actions
      1. vngen_script_execute
      2. vngen_script_execute_ext
  7. Special Thanks
  8. EULA

Creating Custom Animations #

At its core, VNgen is a sequenced animation system with visual novel functions layered on top. Events and actions form a timeline of visual changes, often enhanced by built-in transitions and animation effects. But what if you’ve dreamed up an animation completely unlike the built-in ones? What about animating entities after their transitions have already completed? What about performing entire animations in a single event?

With VNgen’s keyframe animation scripts, all of these things are possible.


Intro to Keyframes

In animation (both digital and otherwise), a keyframe represents a significant change in motion. Rather than produce an animation one subtle frame at a time, creators focus only on the start and end of each motion, resulting in a sequence that roughly portrays how the final animation will play out. Once all the keyframes are in place, it’s much easier to fill in the gaps with frames in between, smoothly transitioning from one keyframe to the next.

In VNgen, these “in-betweens” are generated automatically, meaning all you have to worry about are the keyframes themselves. Set any properties you want to change in a keyframe and they’ll smoothly interpolate to their new values.


Animatable Properties

Keyframe animations come in three categories: transitions, transforms, and deforms. The syntax for writing all three is the same; fundamentally, the only difference is which properties they animate.

As animations represent temporary changes to the entity being animated, VNgen does not modify animated properties directly. Instead, it passes certain values into animation scripts, checks keyframes for changes, and reads the results back into the animated entity in real-time. Not only does this preserve the entity’s original values, but provides a common set of input and output values just for writing keyframe animations.

Note: Another consequence of animations being temporary is that any animatable properties not specified in a keyframe will be interpreted as their default values. For this reason, even if a modified property isn’t meant to change for several keyframes, it must be declared in every keyframe for the modification to persist.

First, the output, or modifiable values:

Transitionable Properties

General properties Type Description
trans_left real Relative left crop
trans_top real Relative top crop
trans_width real Relative width crop
trans_height real Relative height crop
trans_x real Relative horizontal position
trans_y real Relative vertical position
trans_xscale real Relative horizontal scale multiplier
trans_yscale real Relative vertical scale multiplier
trans_rot real Relative rotation, in degrees
trans_alpha real (0-1) Relative alpha value
trans_ease integer/macro Ease mode for the current keyframe


Transformable Properties

General properties Type Description
anim_x real Relative horizontal position
anim_y real Relative vertical position
anim_xscale real Relative horizontal scale multiplier
anim_yscale real Relative vertical scale multiplier
anim_rot real Relative rotation, in degrees
anim_col1 color Top-left gradient color
anim_col2 color Top-right gradient color
anim_col3 color Bottom-right gradient color
anim_col4 color Bottom-left gradient color
anim_alpha real (0-1) Relative alpha value
anim_ease integer/macro Ease mode for the current keyframe
Perspective Only
anim_xoffset real Relative perspective horizontal ‘angle’
anim_yoffset real Relative perspective vertical ‘angle’
anim_zoom real Relative perspective zoom multiplier
anim_strength real Relative perspective parallax strength multiplier

Note: Some perspective animation properties are mapped to general properties and can be used interchangeably: anim_zoom = anim_xscale and anim_strength = anim_yscale. Only anim_xoffset and anim_yoffset are unique to perspective.


Deformable Properties

Properties Type Description
integer The number of columns in the deform mesh
integer The number of rows in the deform mesh
def_xpoint[0, 0] … def_xpoint[1, 3]
real Mesh point horizontal offsets
def_ypoint[0, 0] … def_ypoint[1, 3]
real Mesh point vertical offsets
def_ease real Ease mode for the current keyframe

Note: Deformations cannot be performed on the perspective, therefore there are no special deformable properties.

As you’ve probably noticed, most animatable properties are not only temporary, but relative to the entity’s current properties. This means that setting anim_x to 50, for example, would offset the animated entity by 50 pixels to the right of its current position, rather than to the 50th horizontal pixel in the room. This is especially important for deformations, which would otherwise constrain all animated entities to the same shape!

Even so, there are still times when it is useful to know some of the animated entity’s original properties. This way, animations can be made that adapt to a variety of shapes and sizes without modification. As such, VNgen also passes certain input properties to animation scripts.

General Properties Type Description
input_width real The current entity width
input_height real The current entity height
input_x real The current entity horizontal room position
input_y real The current entity vertical room position
input_xscale real The current entity horizontal scale multiplier
input_yscale real The current entity vertical scale multiplier
input_rot real The current entity rotation, in degrees
Perspective Only
input_zoom real The current perspective zoom
input_strength real The current perspective parallax strength multiplier

Note: As with the corresponding output properties, perspective input properties are mapped to general properties and can be used interchangeably: input_zoom = input_xscale and input_strength = input_yscale

These values cannot be modified, and represent the properties of the entity currently being animated. Transitions, transforms, and deforms all have access to them, so don’t hesitate to include them in your scripts!


A Simple Transform

Now that you’re familiar with the concept of keyframes and which properties can be animated with them, it’s time to start creating keyframe animation scripts of your own!

To begin, create a new script in your project’s asset browser and add your first keyframe:


if (keyframe()) {

If you’re already comfortable with Q-script, this syntax should be quite familiar to you. In a sense, VNgen keyframes behave like stripped-down Quantum events, only instead of populating them with actions, we’ll need to populate them with animation properties instead. In keeping with our earlier example, a simple keyframe would look something like this:


if (keyframe()) {
   anim_x = 50;

At this point, we already have a complete animation: the animated entity will move 50 pixels to the right, then move back even though we haven’t told it to. When an animation ends, all modified properties are smoothly returned to their default values over the same duration as other keyframes. You can think of it as an ‘invisible’ keyframe automatically placed at the end of every script.

Of course, this all assumes the animation isn’t looped. If it is, the entity will appear to get stuck with a 50-pixel offset since our one keyframe will be repeated over and over without end. To create a meaningful loop, we’ll need to add a second keyframe as well:


if (keyframe()) {
   anim_x = 50;

if (keyframe()) {
   anim_x = -50;

Now the entity will shift 50 pixels to the right, then 100 pixels to the left, ending up 50 pixels left of its original position. If the animation is looped, it will continue bouncing 100 pixels back and forth for as long as we allow the animation to run. And of course, there’s no limit to how many keyframes we include in our animation, or how many properties we modify in a single keyframe. Perhaps we should add a little rotation too? How about an ease effect for impact?


if (keyframe()) {
   anim_x = 50;
   anim_rot = -5;
   anim_ease = ease_bounce_out;

if (keyframe()) {
   anim_x = -50;
   anim_rot = 5;
   anim_ease = ease_bounce_out;

Once your animation is complete, save the script and execute it with a vngen_*_anim_start action. It really is that simple!


A Simple Transition

The same principles of regular animations apply to transitions as well, but with a few key differences:

First, transitions can only be applied with vngen_*_create and vngen_*_destroy scripts.

Second, on create, an entity jumps directly to the values specified in the first keyframe of a transition animation (instead of interpolating there from its default values). This makes single-keyframe transitions much more useful than regular animations, since a second keyframe is always implied. For example, the transition:

if (keyframe()) {
   trans_alpha = 0;

… would cause the entity to fade in from an alpha of 0 to a default alpha of 1 at the time of create, or fade out from the current alpha to 0 at the time of destroy.

Third, while other animations can be played forwards or backwards at will, a transition’s direction is determined by when it occurs. Create transitions always perform forwards, while destroy transitions always perform in reverse.

Keep these simple differences in mind and you’ll be making your own transitions in no time!


A Simple Deform

What might not be so simple is applying the same logic to deforms. It’s relatively easy to form a mental image of what changing an entity’s position and rotation will look like, but deforms can be much harder to imagine. However, in principle the two types of animations are the same.

Consider the following example:

Tip: Enabling VNgen’s built-in debug mode will display overlays like the example above on all active deform animations in real-time

When a deform is applied to a VNgen entity, it switches from the standard drawing process to being drawn as a mesh of triangles. These triangles are mapped to a grid of points forming columns (the X axis) and rows (the Y axis). By default, deforms are assumed to be two columns wide and four rows tall, giving a range of points from [0, 0] to [1, 3]. Other subdivisions can optionally be specified inside a special keyframe labeled simply ‘deform’ and placed at the top of your deformation script.

if (deform()) {
   def_width = 2;
   def_height = 4;

In the above example, the deform width (columns) and height (rows) are set to the default values, in which case including this section is not necessary and can be left out of the deformation script. For the purposes of this documentation, these defaults will be assumed.

Rather than modify global properties like position and rotation, deformation animations manipulate each point’s X and Y coordinates to stretch the final image into different shapes.

Note: Simulated image

In this example, all we’ve done is modify the X position of points [0, 1], [1, 1], [0, 3], and [1, 3], much like in the example of a transform animation. The similarity becomes even more apparent when written as a keyframe:


if (keyframe()) {
   def_xpoint[0, 1] = 50; def_xpoint[1, 1] = -50; 
   def_xpoint[0, 3] = 50; def_xpoint[1, 3] = -50;

And again, if we wanted to reverse the effect for an endless loop, we could simply create a second keyframe modifying points [0, 0], [1, 0], [0, 2], and [1, 2] instead:


if (keyframe()) {
   def_xpoint[0, 1] = 50; def_xpoint[1, 1] = -50; 
   def_xpoint[0, 3] = 50; def_xpoint[1, 3] = -50;

if (keyframe()) {
   def_xpoint[0, 0] = 50; def_xpoint[1, 0] = -50; 
   def_xpoint[0, 2] = 50; def_xpoint[1, 2] = -50;

Note that the second keyframe does not define X points [0, 1], [1, 1], [0, 3], and [1, 3]. This would only be necessary if we wanted them to maintain their positions from the first keyframe or shift positions again. In VNgen animation scripts, any undefined properties in a given keyframe will be returned to their default values, therefore each point from the first keyframe will be treated as 0.

Also note that in this example, point values are arranged in a grid imitating each point’s physical position relative to one another. This is a great way to visualize your keyframes as you write them.

With keyframes such as these in place, we can now save the script and execute it with a vngen_*_deform_start action. Don’t let the 2D structure intimidate you: mesh deforms are really quite simple and just as easy to create as transform animations.


Creating ‘Living’ Characters

While many entities in VNgen support deform animations, a prime use-case is characters. Characters are drawn as a composite texture of one or more sprites comprising the body, face, and any other elements you may desire. Using character attachments, it is possible to draw separate sprites for hair, clothing, even individual limbs and beyond! And as unique entities themselves, each attachment, or ‘layer’, can have its own animations of any kind. Try creating custom deform scripts for each attachment and watch your characters come to life!

For full details, see the Characters & Attachments section.

Last updated on June 3, 2018
Suggest Edit