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.8#

Added support for rectangular collision masks (bounding boxes) on options and buttons
- Existing button/option sprites may need to have their bounding boxes manually adjusted if hotspots seem inaccurate
- Transparent sprites will not be clickable at all without manual bounding box adjustment!
Updated vngen_log_add to include support for per-entity lineheight
- Existing instances of this function must be updated to match the new syntax
- If no custom lineheight is desired, use vngen_get_lineheight(all, vngen_type_text)
- (Recommended: use global search & replace)

Updated input functions to use clearer nomenclature and support explicit true/false settings, not just toggles

A table of old functions and their new names is listed below. Existing instances of these functions must be renamed to match the new nomenclature and have arguments added to match the new syntax

Old Syntax		New Syntax
`show_debug_vngen([enable])`	🠺	`vngen_do_debug(toggle, [sound])`
`vngen_continue([sound])`	🠺	`vngen_do_continue([sound])`
`vngen_toggle_auto(delay, [sound])`	🠺	`vngen_do_auto(toggle, [delay], [sound])`
`vngen_toggle_pause([sound])`	🠺	`vngen_do_pause(toggle, [sound])`
`vngen_toggle_visible([sound])`	🠺	`vngen_do_ui_display(toggle, [stop], [sound])`
`vngen_toggle_log([sound])`	🠺	`vngen_do_log_display(toggle, [sound])`
`vngen_log_nav(amount)`	🠺	`vngen_do_log_nav(amount)`
`vngen_log_nav_touch()`	🠺	`vngen_do_log_nav_touch()`
`vngen_log_play_audio()`	🠺	`vngen_do_log_play()`
`vngen_log_button_nav(amount)`	🠺	`vngen_do_log_button_nav(amount)`
`vngen_log_button_select([id])`	🠺	`vngen_do_log_button_select([id])`
`vngen_button_nav(amount)`	🠺	`vngen_do_button_nav(amount)`
`vngen_button_select([id])`	🠺	`vngen_do_button_select([id])`
`vngen_option_nav(amount)`	🠺	`vngen_do_option_nav(amount)`
`vngen_option_select([id])`	🠺	`vngen_do_option_select([id])`

(Recommended: use global search & replace)

Updated vngen_set_lineheight to support per-entity lineheight multipliers
- This required adding two new arguments to vngen_set_lineheight for inputting an entity ID and type
- Existing instances of this function must be updated to match the new syntax
- (Recommended: use global search & replace)
Updated negative pause values to be interpreted as timed delay while auto mode is enabled (rather than indefinite)
- While no change is generally required, it is important to note that existing events and [pause] markup will now exhibit different behavior while auto mode is enabled
- To revert to the old behavior, use vngen_set_auto_type
- There is no change in behavior when auto mode is disabled
Updated easing macros for simplicity
- All *_in_out macros have been renamed to their plain counterparts, e.g. ease_quad_in_out is now just ease_quad
- Existing instances of these macros must be renamed to match the new syntax
- (Recommended: use global search & replace)
Updated auto prompts to match text scale and rotation, not just position
- Any prompt modification actions made to match these properties manually can and should be removed
- (Recommended: use global search & replace)
Renamed vngen_get_structure to vngen_get_struct for brevity and consistency
- Existing instances of this script must be renamed to match the new syntax
- (Recommended: use global search & replace)
Removed legacy animation speed multipliers in favor of GameMaker Studio 2 individual sprite speeds
- All sprite assets must be updated to use the intended framerate, either using the GUI or sprite_set_speed
- Existing instances of vngen_object_draw, vngen_log_draw, vngen_emote_create, and vngen_emote_create_ext must be updated to remove speed arguments
- (Recommended: use global search & replace)
Replaced individual vngen_set_vol_* scripts with a single vngen_set_vol script and audio type macros
- Existing instances of the old scripts must be updated to use the new syntax
- See Macros & Keywords for details
- (Recommended: use global search & replace)

1.0.7#

The vngen_option script now requires an ID to be assigned for the entire option block
- This is required so that user choices can be saved and restored later
- Existing instances of this script must be updated to include a real or string ID
- (Recommended: use global search & replace)

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_ext 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 (EA)#

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 (EA)#

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 (EA)#

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 (EA)#

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 (EA)#

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 (EA)#

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 (EA)#

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 (EA)#

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)