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

Macros & Keywords #

!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.

For the sake of memorability and forwards-compatibility, many VNgen constants use keyword counterparts (or macros) interchangeably with their numeric values. This section covers both, listing available keywords and their numeric counterparts for you to better understand their relation to each other and to the functions in which they are used. However, it is strongly recommended to always use keywords when available, as their numeric values may change in future updates.

It is important to note that not every macro is supported by every script, and as such using macros in undocumented ways may not have the intended effect, or no effect at all. To learn which macros are supported by which arguments and functions, refer to the full reference guide. However, most macros should be self-explanatory.

Tip: Many keywords are prefixed, meaning you don’t have to memorize every keyword to use them. Simply begin typing the first few letters of a keyword in your code editor and you’ll be shown auto-complete options to choose the desired keyword from a list.

Miscellaneous

Keyword/Macro Value Description
auto -1 Defers to the engine to determine a value automatically
previous -1 Does not change the current value from its previous definition
inherit -2 Retrieves an external value stored in memory
any -3 A general selector to apply a modification to all qualifying entities
none -4 Disables a value from being used

 

Animations

Keyword/Macro Value Description
anim_zoom anim_xscale Used in animations designed for the perspective. Same as anim_xscale to other entities.
anim_strength anim_yscale Used in animations designed for the perspective. Same as anim_yscale to other entities.
input_zoom input_xscale Used in animations designed for the perspective. Same as input_xscale to other entities.
input_strength input_yscale Used in animations designed for the perspective. Same as input_yscale to other entities.

 

Easing/Tweening

Keyword/Macro Value Description
ease_none -4 Sets the animation ease mode to linear math, or no easing
ease_sin_in_out 1 Sets the animation ease mode to sine math at the start and end
ease_sin_in 2 Sets the animation ease mode to sine math at the start only
ease_sin_out 3 Sets the animation ease mode to sine math at the end only
ease_quad_in_out 4 Sets the animation ease mode to quadratic math at the start and end
ease_quad_in 5 Sets the animation ease mode to quadratic math at the start only
ease_quad_out 6 Sets the animation ease mode to quadratic math at the end only
ease_cubic_in_out 7 Sets the animation ease mode to cubic math at the start and end
ease_cubic_in 8 Sets the animation ease mode to cubic math at the start only
ease_cubic_out 9 Sets the animation ease mode to cubic math at the end only
ease_quart_in_out 10 Sets the animation ease mode to quartic math at the start and end
ease_quart_in 11 Sets the animation ease mode to quartic math at the start only
ease_quart_out 12 Sets the animation ease mode to quartic math at the end only
ease_quint_in_out 13 Sets the animation ease mode to quintic math at the start and end
ease_quint_in 14 Sets the animation ease mode to quintic math at the start only
ease_quint_out 15 Sets the animation ease mode to quintic math at the end only
ease_expo_in_out 16 Sets the animation ease mode to exponential math at the start and end
ease_expo_in 17 Sets the animation ease mode to exponential math at the start only
ease_expo_out 18 Sets the animation ease mode to exponential math at the end only
ease_circ_in_out 19 Sets the animation ease mode to circular math at the start and end
ease_circ_in 20 Sets the animation ease mode to circular math at the start only
ease_circ_out 21 Sets the animation ease mode to circular math at the end only
ease_rubber_in_out 22 Sets the animation ease mode to exceed values and smoothly fall back at the start and end
ease_rubber_in 23 Sets the animation ease mode to exceed values and smoothly fall back at the start only
ease_rubber_out 24 Sets the animation ease mode to exceed values and smoothly fall back at the end only
ease_elastic_in_out 25 Sets the animation ease mode to exceed values and roughly fall back at the start and end
ease_elastic_in 26 Sets the animation ease mode to exceed values and roughly fall back at the start only
ease_elastic_out 27 Sets the animation ease mode to exceed values and roughly fall back at the end only
ease_bounce_in_out 28 Sets the animation ease mode to bounce between values at the start and end
ease_bounce_in 29 Sets the animation ease mode to bounce between values at the start only
ease_bounce_out 30 Sets the animation ease mode to bounce between values at the end only

Note: See documentation on the interp function for more details on ease modes

 

Origin

Keyword/Macro Value Description
orig_top 0 Triggers vertically aligning the current entity by the top edge
orig_left 0 Triggers horizontally aligning the current entity by the left edge
orig_center -1 Triggers horizontally or vertically aligning the current entity by the center
orig_bottom -2 Triggers vertically aligning the current entity by the bottom edge
orig_right -2 Triggers horizontally aligning the current entity by the right edge

 

Scaling

Keyword/Macro Value Description
scale_none -4 Disables automatic scaling
scale_x_y 1 Triggers automatic scaling to fill the screen in both directions, maintaining aspect ratio
scale_x 2 Triggers automatic scaling to fill the screen horizontally, maintaining aspect ratio
scale_y 3 Triggers automatic scaling to fill the screen vertically, maintaining aspect ratio
scale_stretch_x_y 4 Triggers automatic scaling to fill the screen in both directions, disregarding aspect ratio
scale_stretch_x 5 Triggers automatic scaling to fill the screen horizontally, disregarding aspect ratio
scale_stretch_y 6 Triggers automatic scaling to fill the screen vertically, disregarding aspect ratio
scale_prop_x_y 7 Triggers automatic scaling relative to changes in screen resolution in both directions
scale_prop_x 8 Triggers automatic scaling relative to changes in horizontal screen resolution only
scale_prop_y 9 Triggers automatic scaling relative to changes in vertical screen resolution only

 

Transitions

Keyword/Macro Value Description
trans_none -4 Disables scripted transition animations

 

Entity Types

Keyword/Macro Value Description
vngen_type_perspective 0 Points to the global perspective camera
vngen_type_scene 1 Points to scene entities
vngen_type_char 2 Points to character entities
vngen_type_attach 3 Points to character attachment entities
vngen_type_emote 4 Points to emote entities
vngen_type_textbox 5 Points to textbox entities
vngen_type_text 6 Points to text entities
vngen_type_label 7 Points to label entities
vngen_type_prompt 8 Points to prompt entities
vngen_type_option 9 Points to option entities
vngen_type_audio 10 Points to regular audio entities
vngen_type_vox 11 Points to speech synthesis audio entities
vngen_type_effect 12 Points to scripted effect entities
vngen_type_button 13 Points to button entities
vngen_type_speaker 14 Points to the current active speaker(s) (Exception: not an entity)

 

Last updated on June 3, 2018
Suggest Edit