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

A Simple Choice #

But what if we want to give our players a voice of their own?

VNgen includes actions for creating basic menus, aptly named options. On their own, options only provide an interface for the user to select from a list of items, but by combining options with regular functions such as vngen_goto and a little custom logic, it is possible to use options to jump to different portions of Q-script and create branching narratives across one or more objects.

Put it all together, and a dialog choice might look something like this:

Example:

if (vngen_event()) {

   if (vngen_option(960, 540, 1, 1, snd_hover, snd_select)) {
   
      vngen_option_create("option_good", "I'm doing great!", spr_option, spr_option_hover, spr_option_select, 0, 0, -1, fnt_Arial, c_white, trans_slide_right, 1);
      
      vngen_option_create("option_bad", "Well...", spr_option, spr_option_hover, spr_option_select, 0, 100, -2, fnt_Arial, c_white, trans_slide_right, 1);	
   
   }
   
   switch (vngen_get_option()) {
   
      case "option_good": vngen_goto("event_good"); break;
      
      case "option_bad": vngen_goto("event_bad"); break;
      
   }
   
}

if (vngen_event("event_good")) {

   vngen_text_replace("text", "John Doe", "I'm doing great!", inherit, inherit, 2);

}

if (vngen_event()) {
   
   vngen_script_execute(vngen_goto, "event_complete");
   
}

if (vngen_event("event_bad")) {

   vngen_text_replace("text", "John Doe", "Not so great, I'm afraid...", inherit, inherit, 2);
   
}

if (vngen_event("event_complete")) {

   vngen_text_replace("text", "Jane Doe", "I see.", inherit, inherit, 2);
   
}

Now, such a setup might seem complex at first, but in actuality it relies on all the same processes we’ve already learned.

Creating a complete dialog option sequence consists of three main parts:

  1. Obtaining user input (the choice)
  2. Reacting to user input (the condition)
  3. Providing user feedback (the result)

Let’s break down each step in detail.

 

1. The Choice

The vngen_option script is an action which behaves like an event. It does not replace vngen_event and must be nested inside an event just like any other action. At the same time, however, it possesses its own sub-actions which cannot be run outside the context of vngen_option. Think of a group of options as a single unit―because that’s exactly how VNgen sees it!

Example:

if (vngen_event()) {

   if (vngen_option(960, 540, 1, 1, snd_hover, snd_select)) {
   
      vngen_option_create("option_good", "I'm doing great!", spr_option, spr_option_hover, spr_option_select, 0, 0, -1, fnt_Arial, c_white, trans_slide_right, 1);
      
      vngen_option_create("option_bad", "Well...", spr_option, spr_option_hover, spr_option_select, 0, 100, -2, fnt_Arial, c_white, trans_slide_right, 1);	
   
   }
}

Here we have an options menu with two options to choose from. To simply display a menu, this is all the code we need: one instance of vngen_option as the parent, and one or more instances of vngen_option_create as the child. Although each has its own unique properties, some are also shared. The first two parameters in vngen_option specify the X and Y position to display the menu on the screen, with the X and Y values in vngen_option_create being relative to the parent’s coordinates. The next two values of vngen_option set delays before and after options are created―a pair of values which corresponds to the two transitions set in vngen_option_create. And finally, the two sound effects supplied are only played when an individual option is hovered or selected. The two scripts really are inseparably linked!

For full details on these scripts’ syntax, check out the full reference guide, but for now there’s one other property worth taking note of: the option ID. Not only does this value distinguish different options from one another, but is also the value that will be stored in memory once a selection has been made.

 

2. The Condition

Once the user has input their choice, the selected option’s ID will be stored in memory for future use. No other action is taken automatically―which is by design―meaning it’s up to us to make use of that information however we see fit. The possibilities are practically endless, but the most common way to utilize selected option data is through conditional statements such as ‘if’ or ‘switch’.

Example:

switch (vngen_get_option()) {
   
   case "option_good": vngen_goto("event_good"); break;
      
   case "option_bad": vngen_goto("event_bad"); break;
      
}

For those not familiar, a ‘switch’ statement is like a series of ‘if’ statements strung together in a single group. One condition is tested against multiple cases, and whichever case is found to be true is executed until the ‘break’ statement is reached.

In this scenario, we use the vngen_get_option script to retrieve the ID of the previously-selected option and jump to different Quantum events depending on which option was selected (note how the cases here match the IDs of the options created in the first step). It’s important to note that this value will remain in memory until another options menu is created, which may or may not be desirable depending on how our code is set up. For example, if the selected option remains in memory forever, whatever code we include in our ‘switch’ statement may get executed endlessly as well! For this reason, vngen_get_option will also clear the selected option from memory after it has been retrieved, unless this has been disabled by setting the ‘clear’ argument to false. This guarantees that whatever the result, it will only be triggered once.

Note: vngen_get_option is a very special script. While it is not an action, it does share some behaviors so that it can be used like one. Unlike other VNgen functions, vngen_get_option can be run anywhere in your game―both inside and outside of events!

For our ‘switch’ statement, there are only two possibilities: either the user selected “option_good” or “option_bad”. These options will run vngen_goto and jump to the event labeled “event_good” or “event_bad”, respectively.

 

3. The Result

Of course, using options to trigger vngen_goto means we must have somewhere for the user to go to! As previously mentioned, we can place our “event_good” and “event_bad” labels somewhere in the current object or an entirely different one, but both possibilities can often run into a common problem: how do we keep one option result from running straight into another?

Consider the dialog branches shown in the original example:

Example:

if (vngen_event("event_good")) {

   vngen_text_replace("text", "John Doe", "I'm doing great!", inherit, inherit, 2);

}

if (vngen_event("event_bad")) {

   vngen_text_replace("text", "John Doe", "Not so great, I'm afraid...", inherit, inherit, 2);
   
}

if (vngen_event()) {

   vngen_text_replace("text", "Jane Doe", "I see.", inherit, inherit, 2);
   
}

If the user selects “option_good”, they will respond that they’re feeling well, whereas if they select “option_bad”, they will respond that they’re not feeling so well. These are our two dialog branches, and the intention is for them to converge back onto a single path when the character “Jane Doe” acknowledges their response. Now, this will work just fine if we jump to “event_bad” since the branches converge in the next event, but what about “event_good”?

In this case, we must put a second event between “event_good” and “event_bad” which causes “event_bad” to be skipped if “option_good” is chosen. However, we can’t simply run vngen_goto in an event by itself since it is not an action. Instead, we must wrap it in vngen_script_execute, which takes non-action scripts and executes them in the context of Quantum events. We can also make things easier by assigning a label to the event where our options converge, so we know exactly where to tell vngen_goto to go.

Example:

if (vngen_event("event_good")) {

   vngen_text_replace("text", "John Doe", "I'm doing great!", inherit, inherit, 2);

}

if (vngen_event()) {
   
   vngen_script_execute(vngen_goto, "event_complete");
   
}

if (vngen_event("event_bad")) {

   vngen_text_replace("text", "John Doe", "Not so great, I'm afraid...", inherit, inherit, 2);
   
}

if (vngen_event("event_complete")) {

   vngen_text_replace("text", "Jane Doe", "I see.", inherit, inherit, 2);
   
}

This will cause “event_bad” to be skipped as soon as the player has completed “event_good” and end the options sequence at “event_complete”.

And of course, this is only scratching the surface. By following these same techniques it is possible to create deep dialog sequences and wildly branching narratives, plus entire game menu interfaces and more!

Last updated on June 3, 2018
Suggest Edit