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

At this point we’ve set up VNgen and created a simple dialog sequence complete with interactive responses for the user to choose from. However, if we were to run our game right now, it would look a little bland, having just text. Who are the characters we’ve created, and what do they look like? Where are they? Visual novels being visual, details like these are most often left to context, so it’s important that once the script is in place, other elements are soon to follow.

Fortunately, as previously mentioned, VNgen actions are highly standardized. Now that you have a grasp on creating text, creating other kinds of entities should come naturally. Once you know what entity types are available and what functions they all have, exploring new possibilities is a simple matter of combining your knowledge of the two.

Let’s begin with a scene. VNgen makes it possible to create highly dynamic environments with multiple parallaxing layers, but for now we’ll start with a simple backdrop.

Example:

vngen_event_set_target();

if (vngen_event()) {

   vngen_scene_create("bg", spr_background, 0, 0, 0, false, false, trans_fade, 2);

   vngen_text_create("text", "John Doe", "Hello, world!", 128, 900, 0, 256, fnt_Arial, c_white, trans_fade, 2, true);

   vngen_text_modify_style("text", c_white, c_white, c_gray, c_gray, c_black, c_black, 1, 2);

}

...

Going back to our original example, here we’ve added a background, or scene, to our first event so that our text and environment appear synchronously. Scenes can be created as either backgrounds or foregrounds and also set to endlessly repeat, but aside from these unique properties you’ll notice that, for the most part, creating a scene is quite like creating text. We even have the same selection of transitions to choose from, and can set the transition duration to match that of our text and text style modifications. The only difference is that we assign a sprite to an ID rather than strings.

 

Creating characters is a similar matter, only we’ll also need an extra sprite or two just for facial animations when idle and talking, as seen in the example below.

Example:

vngen_event_set_target();

if (vngen_event()) {

   vngen_scene_create("bg", spr_background, 0, 0, 0, false, false, trans_fade, 2);

   vngen_char_create("John Doe", spr_body, spr_face_idle, spr_face_talk, 0, 1080, 0, 180, 200, false, trans_slide_right, 2);

   vngen_text_create("text", "John Doe", "Hello, world!", 128, 900, 0, 256, fnt_Arial, c_white, trans_fade, 2, true);

   vngen_text_modify_style("text", c_white, c_white, c_gray, c_gray, c_black, c_black, 1, 2);

}

...

Note how the character created in this example has the same ID as the speaker name assigned in the text action. In order for automatic animations to function, both names must match exactly. If they don’t, both the text and character will still display properly, but facial animations will not be played in-sync with text.

Typically, faces should be rendered separate from the body into their own sprites, which are then composited onto the body in real-time in VNgen. This avoids unnecessarily drawing the body over and over while only the face is changing, constituting wasted performance and storage space. Face sprites need not even match body sprite dimensions, since vngen_char_create includes a second set of X/Y coordinates just for where to position the face relative to the body sprite.

And that’s not all. We can save even more performance when creating our other character as well:

Example:

...

if (vngen_event()) {

   vngen_char_create("Jane Doe", spr_body, spr_face_idle, spr_face_talk, 0, 1080, 0, 180, 200, true, trans_slide_left, 2);

   vngen_text_replace("text", "Jane Doe", "I'm good, thanks! How about you?", previous, previous, 2);

}

...

Notice anything different? Aside from the name, another subtle change here makes a big difference in how our second character is displayed. Note the ‘true’ value here―as explained in the full reference guide, this value enables flipping the character horizontally so that only one version of a character needs to be created, facing either direction, since VNgen can mirror the character in real-time later.

 

At this point our scene is beginning to look a bit more alive. Perhaps even a bit too much. Busy backdrops can often lack contrast with text, making it difficult or unpleasant to read. Fortunately, the solution is simple:

Example:

vngen_event_set_target();

if (vngen_event()) {

   vngen_scene_create("bg", spr_background, 0, 0, 0, false, false, trans_fade, 2);

   vngen_char_create("John Doe", spr_body, spr_face_idle, spr_face_talk, 0, 1080, 0, 180, 200, false, trans_slide_right, 2);

   vngen_textbox_create("textbox", spr_textbox, 0, 1080, 0, trans_wipe_right, 2);

   vngen_text_create("text", "John Doe", "Hello, world!", 128, 900, 0, 256, fnt_Arial, c_white, trans_fade, 2, true);

   vngen_text_modify_style("text", c_white, c_white, c_gray, c_gray, c_black, c_black, 1, 2);

}

...

That’s right: a textbox. As textboxes are purely decorative, they are one of the simplest and most standard of all VNgen entities. Text is not physically confined to them in any way, but they still serve an important purpose in making text readable, and even play a role in setting the mood for your particular story and setting. On one hand, it’s a finishing touch, and on the other, it’s just the beginning of a much bigger design language encompassing the entire UI.

 

And indeed, from here, the possibilities are endless. From further UI elements like prompts to advanced composite character attachments, with an understanding of the fundamental principles of VNgen content creation the power is yours to build engaging, interactive narratives full of animated characters and environments. Take the knowledge you’ve gained from creating your first visual novel and you’ll be a master storyteller in no time!

Last updated on July 2, 2018
Suggest Edit