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

Setup & Installation #

1. Obtaining VNgen

VNgen is available for purchase in two forms:

  1. As a GameMaker Marketplace asset
  2. As a standalone extension

Both versions are functionally equal, however the setup process differs slightly depending on which version of VNgen you have purchased.

 

2a. Installation – Marketplace

Installing an asset purchased from the GameMaker Marketplace is easy.

  1. First, open GameMaker Studio and create a new project, or open an existing project you wish to add VNgen into.
  2. Choose the Marketplace tab at the top of the screen and select My Library. If you are not currently logged in to your YoYo Games account, you may be prompted to do so before accessing your asset library.
  3. Once you have purchased VNgen, it will appear in your asset library window. You may download it now by clicking the download icon.
  4. Once VNgen is downloaded, click the import icon and choose Add All, then Import.
  5. VNgen will be added to the current project.

To update an existing project, simply delete all VNgen folders and follow the steps above again. (Make sure to back up any custom code and assets you may have added to the VNgen folders beforehand.)

 

2b. Installation – Extension

Installing an asset from a standalone extension follows a similar process as a Marketplace asset, however the extension will not be added to your Marketplace library.

GameMaker Studio 1.x

To Install:

  1. First, download the extension anywhere on your hard drive and extract it, if necessary.
  2. Next, open GameMaker Studio and create a new project, or open an existing project you wish to add VNgen into.
  3. In your project’s Resources panel, right-click on the Extensions folder and choose Import Extension.
  4. Locate the extension (*.gmez) on your hard drive and import it.
  5. Right-click on the imported extension and choose Import Resources.
  6. Choose Import All, then OK.
  7. VNgen will be added to the current project.

To Update:

  1. First, download the updated extension anywhere on your hard drive and extract it, if necessary.
  2. Next, open your existing GameMaker Studio project.
  3. In your project’s Resources panel, delete all VNgen folders and files, aside from any custom assets you have created.
  4. Right-click on the Extensions folder and choose Import Extension.
  5. Locate the extension (*.gmez) on your hard drive and import it.
  6. Right-click on the imported extension and choose Import Resources.
  7. Choose Import All, then OK.
  8. The latest version of VNgen will be added to the current project.

 

GameMaker Studio 2.x

To Install:

  1. First, download the extension anywhere on your hard drive and extract it, if necessary.
  2. Next, open GameMaker Studio and choose File > Import Project.
  3. Locate the project archive (*.yyz) on your hard drive and import it.
  4. Select a location to save a new VNgen project, as prompted.
  5. VNgen will be added to a new project.

To Update:

  1. First, download the extension anywhere on your hard drive and extract it, if necessary.
  2. Next, locate the project archive (*.yyz) and open it as a compressed file/folder (not with GameMaker Studio 2) (No compression software? Use 7-zip.)
  3. Locate the project you wish to update on your hard drive.
  4. Select the folders you wish to update from the project archive and extract them to the project on your hard drive, choosing to overwrite files when prompted. (It is recommended to exclude the options and views folders.)
  5. The latest version of VNgen will be added to the project.

 

3. Project Setup

Once VNgen is added to your project, you may proceed to create content with it! Demo objects are included to get you started, but there are times when you may wish to start from scratch as well.

!Important note: GameMaker Studio 1.x users must import the included macros.txt file located in the Included Files folder before using VNgen. This can be done from the Resources > Define Macros menu and selecting Load.

To start, you’ll need to create two objects: these will be used as a backlog and script, respectively. (Using a backlog is optional, but recommended.) VNgen is highly flexible and can operate in a wide variety of configurations, but for standard functionality you should set up your objects to run the following functions in the corresponding events:

 

Backlog Object

  • Create Event

    • vngen_log_init(50);
  • Step Event

    • vngen_log_nav_touch();
  • Draw GUI Event

    • vngen_log_draw(spr_log_bg, spr_divider, spr_audio_off, spr_audio_on, 64, display_get_gui_width()*0.75, inherit, inherit, 1);
  • Press Up Event

    • vngen_log_nav(-1);
  • Press Down Event

    • vngen_log_nav(1);
  • Press Space Event

    • vngen_log_play_audio();
  • Press L Event

    • vngen_toggle_log();

 

Script Object

  • Create Event

    • vngen_object_init();
  • Step Event

    • vngen_event_set_target();
    • if (vngen_event()) {
      //Actions
      }
    • vngen_event_reset_target();
  • Global Mouse Left Released Event

    • vngen_continue(snd_continue);
  • Draw Event

    • vngen_object_draw(0, 0, 1, true);
  • Release Enter Event

    • vngen_option_select();
  • Press Up Event

    • vngen_option_nav(-1);
  • Press Down Event

    • vngen_option_nav(1);
  • Press A Event

    • vngen_toggle_auto(3);
  • Press V Event

    • vngen_toggle_visible();
  • Press Escape Event

    • vngen_toggle_pause();

 

Each of these functions will be covered in detail later, so for now just think of this as a standard VNgen configuration. Especially take note of the script object’s Step Event, as this is where most of the VNgen magic will take place.

Once your objects are set up and placed in the room of your choice, you’re ready to move on to the next section: learning to create with Q-script.

Last updated on June 13, 2018
Suggest Edit