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

Compatibility Notes #

Some updates include certain changes which require existing projects to be modified to retain compatibility with updated versions. This section documents those changes as well as the remedies to any incompatibilities they create.

1.0.6

  • Renamed vngen_perspective_modify to vngen_perspective_modify_pos for consistency with other functions
    • Existing instances of this function must be updated to match the new nomenclature
    • (Recommended: use global search & replace)
  • Removed vngen_get_renderlevel for consistency with other vngen_set_* functions which have no comparable vngen_get_* function
    • Retrieving the values of these properties is only necessary for advanced usage, and can be handled by addressing the property variable directly; in this case, vngen_get_renderlevel() can be replaced with global.vngen_renderlevel
    • (Recommended: use global search & replace)

 

1.0.4

  • Added support for built-in cursor states to vngen_set_cursor
    • Previously, -1 could be used to reset cursors to their defaults. This value has now been changed to -4 (or keyword ‘none’) to avoid conflicts with the cursor state cr_none, which is a valid cursor
    • Existing instances of this function using -1 to reset cursors must be updated to keyword ‘none’ to match the new standard
    • (Recommended: use global search & replace)
  • Added support for auto text positioning in extended option and button functions
    • As ‘auto’ is also interpreted as -1, text offsets previously at an X or Y coordinate of -1 will need to be changed to other values (e.g. 0 or -2) to avoid enabling auto positioning
    • (Recommended: use global search & replace)

 

1.0.3

  • Added ‘auto’ keyword support to vngen_text_create_* actions to better facilitate NVL-style presentation
    • As ‘auto’ is also interpreted as -1, text entities previously created at an X or Y coordinate of -1 will need to be changed to other values (e.g. 0 or -2) to avoid enabling auto positioning
    • (Recommended: use global search & replace)

 

1.0.0

  • Added vngen_count to replace individual entity *_count functions with a universal function
    • Existing instances of *_count functions (e.g. vngen_option_count) must be replaced with the new function (e.g. vngen_count(vngen_type_option))
    • This does NOT include events, which are not entities and therefore still have their own vngen_event_count function
    • (Recommended: use global search & replace)
  • Added ‘previous’ keyword support to character face coordinates in character replace actions
    • As ‘previous’ is equivalent to -1, faces positioned at coordinates -1, -1 must be repositioned.
    • (Recommended: adjust sprite offsets to compensate and use global search & replace)
  • Added ‘full’ keyword support to vngen_audio_modify loop clip settings
    • Existing instances of vngen_audio_modify using clip settings must add a new argument to enable or disable playing from the current position before clipping
    • This does NOT include instances where clip settings are not used, as clip arguments are optional
    • (Recommended: use global search & replace)
  • Added *_transformed functions to VNgen options, replacing the extra color functionality previously added to vngen_option_create_ext
    • Existing instances of vngen_option_create_ext must have hover and select color arguments removed
    • Alternatively, instances of this script may be replaced with either vngen_option_create_transformed or vngen_option_create_ext_transformed
    • (Recommended: use global search & replace)
  • Updated log buttons to match the new button standard
    • Existing instances of vngen_button_create must be rewritten to match the updated syntax
    • In order for buttons to scroll the log as before, vngen_get_log_button must be run in the log object Step event to execute vngen_log_nav when buttons are selected (see included demo objects for examples)
  • Replaced per-entity text speed with vngen_set_speed, which sets speed for all text entities.
    • Existing instances of vngen_text_create, vngen_text_create_ext, and vngen_text_replace_exit must be modified to remove the “speed” argument.
    • Text speed should now be set with vngen_set_speed in the Create Event, or in VNgen events with vngen_script_execute_ext.
    • (Recommended: use global search & replace)
  • Replaced vngen_instance_create with vngen_instance_change
    • Existing instances of vngen_instance_create must be replaced with either the new function or the standard instance_create function coupled with vngen_object_clear (if destroying the current object is desired)
    • (Recommended: use global search & replace)
  • Replaced bracket escape character with ^
    • Existing instances of escaped markup must be replaced with the new syntax, i.e. \[ becomes ^[
    • This does NOT apply to the newline character, which is still \n
    • (Recommended: use global search & replace)
  • Removed vngen_option_exists as its functionality has been superseded by vngen_exists
    • Existing instances of vngen_option_exists must be replaced with vngen_exists(any, vngen_type_option)
    • (Recommended: use global search & replace)
  • Removed language macros as they have been superseded by vngen_type_* macros
    • Existing instances of lang_text and lang_audio must be replaced with vngen_type_text and vngen_type_audio
    • The lang_all macro has no replacement, and the ‘type’ argument in vngen_set_lang can now be omitted to set both types simultaneously instead
    • Instances of vngen_set_lang and vngen_get_lang using integers instead of macros to set type do not need to be changed
    • (Recommended: use global search & replace)
  • Removed ef_hap_ramp_down and renamed ef_hap_ramp_up to ef_hap_ramp
    • As effects and animations can now be reversed, bidirectional ramp scripts were no longer necessary
    • Existing instances of the old effects must be renamed to ef_hap_ramp and reversed if desired
    • (Recommended: use global search & replace)

 

0.9.9 (Early Access)

  • Added min/max pitch arguments to vox actions. Pitch is now randomized between these two values, rather than being a switch enabled by setting pitch to -1
    • Existing instances of vngen_vox_play and vngen_vox_modify must be updated to include a second pitch argument.
    • Pitch must now be written as min/max values. Using -1 or keyword ‘auto’ for random pitch is now invalid.
    • (Recommended: use global search & replace)
  • Rearranged vngen_vox_play arguments so that pitch comes before volume for consistency with other audio functions.
    • Existing instances of this script must be updated to have their argument order switched to match this change.
    • (Recommended: use global search & replace)
  • Updated effects to use custom variable array
    • Existing effect scripts must be updated to reflect this change. Effect variables previously named “ef_var0”, “ef_var1”, and so forth must now be written as “ef_var[0]” and “ef_var[1]”.
    • More than 16 variables can now be used with this method. Any previous workarounds may be replaced with the built-in system.
    • (Recommended: use global search & replace)
  • Updated deforms to use 2D point arrays
    • Existing deform scripts must be updated to reflect this change. Deformation variables previously named “def_xpoint0”, “def_xpoint1”, and so forth must now be written as “def_xpoint[0, 0]” and “def_xpoint[1, 0]”.
    • Points are now properly treated as a grid of columns and rows ranging from [0, 0] to [1, 3], not a linear range of 0-7.
    • (Recommended: use global search & replace)

 

0.9.8 (Early Access)

  • The make_color_hex function has been renamed make_color_hex_to_rgb for consistency with its new opposite function, make_color_rgb_to_hex.
    • Existing instances of make_color_hex must be renamed.
    • (Recommended: use global search & replace)
  • Audio wrappers have been removed in preparation of v1.0. If you have not updated to the new audio functions yet, you must do so now.
    • Existing instances of old audio and vox functions must be renamed
    • (Recommended: use global search & replace)
  • Fixed incorrect scaling when launched directly in fullscreen by sampling base resolution when vngen_set_scale is run.
    • This means unlike previous versions, vngen_set_scale should NOT be run in the Step event or any event where it will be executed repeatedly. Ideally, vngen_set_scale should ONLY be run in the Create event instead.

 

0.9.7 (Early Access)

  • Updated vngen_log_draw to allow changing separation between entries.
    • Existing instances of this script must be updated to include a separation value (default 64).
    • (Recommended: use global search & replace)
  • Replaced vngen_set_legacy with vngen_set_renderlevel.
    • Existing instances of the old function must be replaced with the new one.
    • While it is not required to change the values set in the old function, optional new values are also available. It is recommended to see documentation on the new function before updating.
    • (Recommended: use global search & replace)

 

0.9.6 (Early Access)

  • Externalized transitions as a new category of keyframe animations.
    • Transitions are now referenced as scripts, not macros, and any instances of their old numeric equivalents will need to be updated to match the new script names.
    • No change is necessary if macros were used as intended.
    • The trans_none macro is still valid and can still be used to disable transitions. This is NOT the same as the numeral 0, which can no longer be used to disable transitions.
    • Transitions out are now reversed from transitions in. For transitions with directional counterparts, this may require switching directions to retain previous behavior.
    • (Recommended: use global search & replace)
  • Added support for performing animations, deformations, and effects in reverse.
    • Existing instances of vngen_*_anim_start, vngen_*_deform_start, and vngen_effect_start must be updated to include a ‘reverse’ argument.
    • (Recommended: use global search & replace)

 

0.9.5 (Early Access)

  • Updated tiled scenes to behave like standard scenes.
    • Adjustments being made to compensate for old tiled scenes can be removed
    • Alternatively, the old style of tiled scenes can be kept by running vngen_set_legacy(true).
  • Removed scale from perspective calculations.
    • Elements relying on scale for changes to parallax strength must have z-index adjusted to compensate (ratio of z-index to scale is 100:1)
  • Fixed character flipping in vngen_char_replace_ext being absolute instead of relative
    • Existing instances of vngen_char_replace_ext must be updated to set the intended character orientation
    • (Recommended: use global search & replace)

 

0.9.4 (Early Access)

  • Added optional easing support to non-extended actions.
    • Text and label actions using real numbers as language tags must either have a separate ease argument supplied prior to the language tag, or the language tag must be converted to a string
    • All other actions, and text and label actions using string language tags DO NOT require modification
  • Added ‘idle’ argument to vngen_char_create_ext for consistency with vngen_char_replace_ext.
    • This argument was originally omitted due to GameMaker Studio’s 16-argument limitation, which has now been removed.
    • Existing instances of vngen_char_create_ext must be updated to add an ‘idle’ argument.
    • (Recommended: use global search)
  • Added ‘name’ argument to vngen_text_create_ext and vngen_text_replace_ext for consistency with other functions.
    • This argument was originally omitted due to GameMaker Studio’s 16-argument limitation, which has now been removed.
    • Existing instances of vngen_text_create_ext and vngen_text_replace_ext must be updated to add a name argument, or “” for none or if name markup is used instead.
    • (Recommended: use global search & replace)
  • Fixed option position being calculated incorrectly.
    • Existing options using sprite offsets will need to be repositioned to stop compensating for sprite offset, as this is now properly factored into position automatically.
    • (Recommended: use global search & replace)
  • Simplified vngen_option_create in lieu of vngen_option_create_ext.
    • Existing instances of vngen_option_create must be updated to use the new simplified syntax or be replaced with vngen_option_create_ext.
    • (Recommended: use global search)
  • Renamed audio functions for consistency with other VNgen functions.
    • Wrappers have been added which allow using the old syntax, which is consistent with standard GameMaker Studio syntax. However, users are encouraged to switch to the new VNgen naming scheme, as wrappers due incur a small performance penalty.
    • Exception: vngen_sound_modify is wrapped as vngen_modify_sound. Existing instances of vngen_sound_modify must be replaced with either the new VNgen syntax or the GameMaker syntax wrapper.
    • (Recommended: use global search & replace)
  • Renamed vngen_get_option_number to vngen_option_count for consistency with other functions.
    • Existing instances of vngen_get_option_number must be renamed to vngen_option_count.
    • (Recommended: use global search & replace)
  • Renamed vngen_get_option_active to vngen_option_exists for consistency with other functions.
    • Existing instances of vngen_get_option_active must be renamed to vngen_option_exists.
    • (Recommended: use global search & replace)

 

0.9.3 (Early Access)

  • Merged style inheritance data for text and labels, which are now saved and loaded as a single string.
    • Save files generated with previous versions of vngen_file_save will need to be regenerated for style data to persist. For projects spanning multiple VNgen objects, this may require using vngen_goto to revisit previous objects in order to rebuild style data.
  • Renamed vngen_log_get_size to vngen_log_count for consistency with other functions.
    • Existing instances of vngen_log_get_size must be renamed to vngen_log_count
    • (Recommended: use global search & replace)
  • Renamed vngen_get_event to vngen_event_get_index for consistency with other functions.
    • Existing instances of vngen_get_event must be renamed to vngen_event_get_index
    • (Recommended: use global search & replace)
  • Migrated vox audio to its own data structure.
    • No change is required to existing instances of vngen_play_vox.
    • Existing instances of vngen_stop_sound to end vox must be renamed to vngen_stop_vox.
    • (Recommended: use global search & replace)
  • Skipping to event IDs greater than or equal to the total number of events now skips past the final event rather than ending the skip operation when the final event begins.
    • Any instances of vngen_goto using large values to bruteforce skip to the final event must be edited to skip precisely to the event itself.
    • (Recommended: use the new vngen_event_count function to navigate precisely to the final event, minus one)

 

0.9.1 (Early Access)

  • Added vngen_emote_create_ext.
    • Existing instances of vngen_emote_create must be renamed to vngen_emote_create_ext.
    • (Recommended: use global search & replace)
  • Added trans_zoom_out transition and replaced trans_scale with trans_zoom_in.
    • Existing instances of trans_scale must be renamed to trans_zoom_in to complement the new transition.
    • (Recommended: use global search & replace)
  • Reversed argument order in vngen_set_lang for consistency with other functions.
    • Existing instances of vngen_set_lang must have their arguments ordered ‘language’ first, then ‘type’.
    • (Recommended: use global search & replace)
Last updated on September 21, 2018
Suggest Edit