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

In any case, the best way to learn is by doing. With your project prepared as shown in the setup guide, your script object’s Step Event should currently look something like this:

Example:

vngen_event_set_target();

if (vngen_event()) {

   //Actions

}

vngen_event_reset_target();

Now it’s time to start filling those events with actions!

 

Let’s start with some text:

Example:

vngen_event_set_target();

if (vngen_event()) {

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

}

vngen_event_reset_target();

The simplified vngen_text_create script accepts arguments in the following order: ID, speaker name, text, x, y, z, linebreak (or width), font, text color, transition, transition duration, and ease mode. In practice, you won’t need to remember this order since syntax guides will always be provided at the bottom of your code editor window.

In this example, the text “Hello, world!” is assigned to the character “John Doe” and displayed 128 pixels from the left and 900 pixels from the top of the screen. At 256 pixels wide, the text will wrap into a new line, but this should be plenty to fit our text with the chosen font, ‘fnt_Arial’. Furthermore, the text fade onto the screen over a period of two seconds.

Quite a lot of information conveyed in a single, brief line!

 

But what if we want to wipe the screen clean and start a new line of text from scratch? Do we have to destroy the first one and create it again?

While that is certainly possible, there’s a much better way: replacing the text we already created.

Example:

vngen_event_set_target();

if (vngen_event()) {

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

}

if (vngen_event()) {

   vngen_text_replace("text", "John Doe", "How are you?", fnt_Arial, c_white, 2);

}

vngen_event_reset_target();

First, we create a new event. Remember: events are like nodes on a timeline, where everything contained inside an event occurs simultaneously, while events themselves play out in sequence. Since we don’t want our original text to get replaced until the user has read it, that means the replace operation must occur in a separate event.

In the first event, we created a line of text with the ID “text”. Now we can create a new event and manipulate the same line of text by addressing its ID. In the example above, only the line of text being spoken has changed, but if we wanted, we could also change who’s speaking, what font and color the text appears in, and how long to fade from the old text to the new text.

Of course, it’s a bit of a waste to specify all these values again and again if only one property is changing. Fortunately, there’s a way we can simplify our example even more:

Example:

vngen_event_set_target();

if (vngen_event()) {

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

}

if (vngen_event()) {

   vngen_text_replace("text", previous, "How are you?", inherit, inherit, 2);

}

vngen_event_reset_target();

Notice how in this version of the example, the character name, font, and text color aren’t specified at all, but instead use keywords to save space and time. Keywords are macros which trigger special behaviors in certain scripts.

Note: Not all properties support keywords. Refer to the full reference guide to learn which properties support which keywords.

In this case, ‘previous’ is used to set the speaker name to the name used in the previous instance of the text ID “text”. ‘Inherit’ is even more special: each time you specify a new text font or color, it is assigned to the speaker name and stored in memory for the duration of the entire visual novel. And the ‘inherit’ keyword restores that data. This means any custom text styling you’ve done once never has to be done again for that speaker’s text.

In fact, let’s add some style to our character’s text now by modifying the original string:

Example:

vngen_event_set_target();

if (vngen_event()) {

   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);

}

if (vngen_event()) {

   vngen_text_replace("text", previous, "How are you?", inherit, inherit, 2);

}

vngen_event_reset_target();

Our text will now be displayed with a four-color gradient fading vertically from white to gray, along with a black shadow and outline effect. The two-second style change duration matches up with our initial fade transition to ensure text appears seamlessly. From now on, so long as we use the ‘inherit’ keyword for the ‘color’ property on any lines where “John Doe” is the speaker, this gradient will be restored without having to run another vngen_text_modify_style operation again!

Now, let’s take this concept a step further to bring in a second character to interact with:

Example:

vngen_event_set_target();

if (vngen_event()) {

   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);

}

if (vngen_event()) {

   vngen_text_replace("text", previous, "How are you?", inherit, inherit, 2);

}

if (vngen_event()) {

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

}

vngen_event_reset_target();

As you can see, in a single new line, we’ve created a new string of text, assigned it to a new speaker, and passed our first character’s text stylization into the second, effectively combining three actions into one! Just like the ‘previous’ keyword can be used to avoid changing speaker names, here it avoids setting a new font or text color, instead using the gradient set in the first event. Now “John Doe” and “Jane Doe” each have their own copy of the same style, which can be modified later without affecting the other character.

In this way, effective use of available actions makes displaying text both easy and powerful!

Last updated on July 2, 2018
Suggest Edit