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 Effects #

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 transition effects and keyframe animations. But what if you’ve dreamed up an action or animation completely unlike those offered by other systems? What about animating game properties that aren’t part of VNgen at all? What about creating, drawing, and removing custom elements in a single action?

With VNgen’s keyframe effect 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 transition to their new values.

 

Modifiable Properties

Effects are written using two separate categories of keyframes: properties (the ‘keyframe’) and code (the ‘effect’). The syntax for writing standard keyframes is the same as other animations; fundamentally, the only difference lies in the way these properties are used in custom code.

VNgen uses an array of special variables which can be defined as virtually anything for the duration of the effect. However, it is important to note that these variables are temporary, and their values will be reset at the end of each frame (or when the next effect is executed, if any). As such, effect variables should never be used as references to ‘volatile’ data such as surfaces or data structures, as doing so will result in a memory leak.

Note: Another consequence of effect variables being temporary is that any 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.

 

Property Type Description
ef_var[0] … ef_var[#]
real/string Custom variable, default value = 0
ef_ease integer/macro Ease mode for the current keyframe

Although effect values are custom and can serve a wide variety of purposes, for many effects it is helpful to have access to certain outside variables as well. This way, effects can be made that adapt to a variety of scenarios without modification. As such, VNgen also passes certain input properties to effect scripts.

General Properties Type Description
input_rate real The current sprite speed multiplier, adjusted for FPS and delta time
input_width real The current viewport width
input_height real The current viewport height
input_x real The current global horizontal offset defined in vngen_object_draw
input_y real The current global vertical offset defined in vngen_object_draw

These values cannot be modified, and represent properties of the engine itself.

 

A Simple Effect

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 effect scripts of your own!

To begin, create a new script in your project’s asset browser. Before we begin adding keyframes, however, we must first decide what code our effect will execute, which will also determine what properties our variables will behave as.

All effect code is executed under a single keyframe labeled simply ‘effect’:

Example:

if (effect()) {
   //Code
}

While there’s no limit to what code an effect can contain, it’s important to note that all effects will be executed in the Draw event, and as such are unsuitable for performing regular programming tasks. Instead, let’s begin by drawing a colored rectangle which will flash on and off the screen.

Example:

if (effect()) {
   draw_set_alpha(ef_var[0]);
   draw_rectangle(input_x, input_y, input_x + input_width, input_y + input_height, false);
   draw_set_alpha(1);
}

Note how in the example above, ef_var[0] is input as the alpha value even though it hasn’t been declared yet. It’s good practice to plan out your use of available effect variables in this way before beginning to create keyframes. Of course, it would also be possible to use ef_var[1], ef_var[2], ef_var[3], and ef_var[4] as the rectangle x, y, width, height, and so on if we desired, but for the sake of this example we’ll stick to using ef_var[0] as alpha only.

With our code set up and our variables decided, we can now add our first keyframe:

Note: Keyframes may appear before or after effect code. Because execution order is predetermined, where each type of keyframe appears in the script is inconsequential.

Example:

if (keyframe()) {
   //Variables
}

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 effect variables instead. In keeping with our earlier example, a simple keyframe would look something like this:

Example:

if (keyframe()) {
   ef_var[0] = 1;
}

At this point, we already have a complete effect: a white rectangle with the position and size of the perspective camera will fade from fully transparent to fully opaque, then fade back out even though we haven’t told it to. When an effect 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 effect isn’t looped. If it is, the screen will remain white forever 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:

Example:

if (keyframe()) {
   ef_var[0] = 1;
}

if (keyframe()) {
   ef_var[0] = 0;
}

Now the entity will fade in and out regardless of whether loop is enabled or not. If so, the screen will continue to flash for as long as we allow the effect to run. And of course, there’s no limit to how many keyframes we include in our effect, or how many variables we create or modify in a single keyframe.

Once your effect is complete, save the script and execute it with the vngen_effect_start action. It really is that simple!

Last updated on May 4, 2018
Suggest Edit