Topics

[Download AGS 3.5.1 installer]

AGS 3.5.1 - Patch 18

Full release number: 3.5.1.25

Download AGS 3.5.1 installer

Download AGS 3.5.1 as a .zip archive

For Editor

Spoiler

VC 2015 redistributable needed for AGS Editor on Windows

Download Dark UI Theme for the editor

[close]

For Android

Spoiler

Android launcher (APK signed with Debug key), suitable for running any compatible AGS game

Native engine libraries, for making your own signed APKs

[close]

For Engine/Editor developers

Spoiler

AGS source code central repository

Debug symbols database (for analysing crash dumps)

[close]

Released: 5th February 2023

Previous stable version: AGS 3.5.0 P10 forum thread


This release is brought to you by:

- Alan v. Drake
- Crimson Wizard
- Donovan Watteau (fix for big-endian systems)
- eri0o
- fernewelten (fixes)
- James Duong (implemented "--console-attach" option for Windows)
- Morgan Willcock
- Nick Sonneveld
- rofl0r
- Pablo Navarro (fixes)
- Thierry Crozat (bug fixing)
- vga256 (bug fixing)



Summary

3.5.1 is a minor update after 3.5.0, which contains mostly utility additions, fixes and perfomance improvements.


Changes in the Patch 18:

Engine:
- Fixed background speech and textual overlays may disable GUI when being continuously created in repeatedly_execute* kind of functions. (Regression since previous patch).


Changes in the Patch 17:

Editor:
- Fixed GUI.Visible property was resetting to false when PopupStyle is switched to Modal.

Engine:
- Performance improvement in Direct3D/OpenGL renderers, related to plugins which subscribe to render events.
- Fixed renderer error occuring if room background frames are of different sizes.
- Fixed software renderer may have an unpainted black line at the bottom, if there's a GUI or Overlay positioned partially offscreen.
- Fixed GUI buttons could retain mouse-over pic after interface is disabled then enabled (this is a regression since recent patch).
- Fixed crash occuring when user creates too many Overlays in script; will report a scripting error instead.
- Fixed memory leak occuring when the TTF font is drawn partially outside the DrawingSurface.
- Fixed Parser.Said() could lead to a program crash in case there are space-separated words following the comma (e.g. "climb,get in bed").
- Fixed crash occuring if a plugin tried to call SetVirtualScreen().

Plugins:
- Fixed SnowRain plugin drawing particles only in 320x200 bounds.


Changes in the Patch 16:

Editor:
- Fixed autocomplete crashing the editor if there was an import declared with type and variable having identical names, and user tries to type that variable's name and a dot to access its members.
- Fixed newly created Views taking free IDs in the middle of the list in random order instead of a straight one (after you previously deleted some Views).

Engine:
- Added missing "DrawSprite" function for "agsblend" plugin stubs.
- Fixed loading pre-3.5.0 games on big endian systems.
- Fixed GUI buttons not displaying the mouse-over image if the interface state was toggled to enabled state while the mouse was over the button.

Updated the manual with certain fixes and corrected examples of using Camera and Viewport structs.


Changes in the Patch 15:

Editor:
- Fixed crash that could occur when changing View's ID to an unused number in the middle.
- Fixed comments and string literals were styled incorrectly in dialog scripts.
- Fixed unterminated string literals in script were not considered as errors when processing scripts for translation update and autonumbering of speech lines, leading to wrong results.
- Fixed Editor was updating translation file even if errors were found while scanning the scripts, which could cause a TRS corruption.
- Fixed Editor could overwrite changes done manually to TRS while the editor is open and if you run a translation update right after.
- Fixed potential program crash on exit in case an editor's plugin has mistakes in "shutdown" callback. Instead editor will report a component's error, but still close properly after.

Script API:
- Removed a rule that Viewport and Camera with ID 0 can't be deleted.


Changes in the Patch 14:

Editor:
- Do not error when compiling a 256 colors game if Direct3D or OpenGL are selected as a default graphics driver (display a warning instead).
- Fixed crash when trying to import pre-2.60 game projects.


Changes in the Patch 13:

Engine:
- Fixed room object does not update its texture if it had a dynamic sprite assigned to it, and that sprite was unassigned, modified or recreated with same ID, and then reassigned again, - all within the same game frame.
- Fixed normal font renderer is not reinitialized correctly in the engine if a plugin uses IAGSEngine::ReplaceFontRenderer(), passing original renderer's pointer (which it received from the previous ReplaceFontRenderer call).


Changes in the Patch 12:

Engine:
- Fixed GUI textual controls don't redraw when the game translation changes until player clicks on GUI (regression since previous 3.5.1 updates).
- Fixed multitasking mode persisting if the game was switched from windowed to fullscreen mode (even though it's not supposed to work in fullscreen).


Changes in the Patch 11:

Editor:
- Fixed batch sprite export with "Set exported file as sprite source" option was assigning new source paths without file extension.

Engine:
- Perfomance fix: GUIs changing Transparency or Visible state should not redraw their surface.

Compatibility:
- Allow AudioClip.Play to to place clips on a crossfade channel, which is normally unaccessible from script. This prevents errors in some games that relied on this behavior.


Changes in the Patch 10:

Engine:
- Fixed crash when visible viewport does not have any linked camera.
- Fixed ListBox.FillSaveGameList() may include save slots with negative slot number (e.g. when the save file has "*.-01" extension).
- Fixed potential crash after failed RunAGSGame() call.
- Fixed search for the game data by GUID when restoring a save belonging to another game;
  this was implemented in 3.5.1, but appeared to not work correctly.


Changes in the Patch 9:

Editor:
- Removed restriction on max dialog topics in the project. The dialog limit in the engine was removed in 3.4.1, but remained in the Editor by oversight.
- Fixed Audio Clip items in the project tree not displaying their IDs right after being renamed.

Compiler:
- Fixed crash occuring when compiler tries to report "Already referenced name as import" error.

Engine:
- Added "--translation" and "--no-translation" command-line arguments.


Changes in the Patch 8:

Engine:
- Clearer error messages for Get/SetProperty functions.
- Fixed PlayFlic() command fails to start the video (regression in 3.5.1).
- Fixed DrawingSurface.DrawSurface() not applying transparency parameter correctly if the drawn surface has alpha channel.
- Fixed OVERHOTSPOT is not updated immediately when character's name changes while cursor is above that character.

Templates:
- In BASS template fixed right click not dropping currently selected item if cursor was hovering over another item.


Changes in the Patch 7:

Editor:
- Added "Layout -> Reset to Defaults" menu command.
- Editor will now reset panel layout to default state if loading layout fail for any reason.
- Default config is now saved also when the game is run in debug mode (F5). This ensures that the test run is using the latest Default Setup, if the user's config has not been created yet.
- Editor will now display an error if user tried to reserve too many channels for audio types.
- Fixed Editor failing to start if user preferences file is corrupted.
- Fixed "Use old-style custom dialog options API" was not set when importing pre-3.4.0 projects.
- Fixed comboboxes' drop-down arrows were not painted with the right color from a color theme.

Engine:
- Fixed program crash occuring if the game reserved too many channels for audio types.
- Fixed potential crash occuring when player loads a save made in a multi-frame room, but the room was since edited and no longer has as many frames.
- Fixed character may have incorrect Frame (property) values while turning.


Changes in the Patch 6:

Editor:
- Added line numbers in the dialog script editor.
- Fixed Dialog script loosing changes if the pane is closed or redocked.
- Fixed controls arrangement on the Dialog pane getting broken when it's redocked.

Engine:
- Fixed filepaths in scripts that have backslashes ('\') fail on non-Windows systems.
  All the (script) File functions will now convert backslashes in filepaths into forward slashes for compatibility.
- Fixed engine was still creating standard directories for game saves and data, even if user provided the custom paths for these.
- Fixed TextBox control crashing the game if it's empty and player presses Backspace.
- Fixed controls on a fully transparent GUI were not interactive (this is an original AGS behavior, which was unintentionally changed in 3.5.0 by mistake).

Compatibility:
- When running 3.5.0 games, treat fully transparent GUI as non-interactable.
  In AGS transparent GUIs may be still interacted with, but 3.5.0 introduced an unintentional (and undocumented) change to this, which was reverted in 3.5.1.

Android:
- Support global engine's config file when the game is run from the Launcher: it's located in the AGS games' parent directory, same place where android.cfg is.

WinSetup:
- Added "Custom game shared data path" to complement "Custom save path" option.


Changes in the Patch 5:

Contained no changes and was a formal re-release with only fixed program build instructions for Linux.


Changes in the Patch 4:

Editor:
- Fixed swapping of inventory item's numeric ID could lead to errors.
- Fixed crash when importing pre-3.* games with multiple script modules.
- Renamed "Enforce object-based scripting" setting to "Enforce post-2.62 scripting". This is for clarity.

Compiler:
- Fixed potential memory corruption when user script reaches max nested if/else blocks.

Engine:
- Also tell module name and approximate source line when reporting script import errors for the variables and local functions.


Changes in the Patch 3:

Editor:
- Fixed sprite file over 2 GB could not be loaded (regression since the last patch).

Engine:
- Further improvement to GUI perfomance: don't redraw GUI when the mouse cursor is hovering over or interacting with controls not leading to an actual visual change.
- Fixed ListBox items could become unaccessible if its font or height is changed leading to a disabled scrollbar.


Changes in the Patch 2:

Engine:
- Fixed speech lipsync getting disabled after loading another game with RunAGSGame().
- Fixed MOD/XM clips fail to play (regression).
- Fixed certain OGV videos fail to play (regression).
- Fixed software renderer was not updating game screen correctly when running a game with legacy "letterboxed" feature (regression).


Changes in the Patch 1:

Editor:
- Fixed script compiler sometimes was not specifying actual Dialog number when reporting errors in the dialog scripts.

Engine:
- Fixed Game.TranslationFilename always returning empty string (regression).
- Fixed GUI controls which were toggled from disabled to enabled state not responding to the mouse clicks until the mouse is moved (regression).
- Fixed OpenGL did not apply a Linear filter when "Render sprites in screen resolution" option is off.


What is new in 3.5.1

Editor:
- Added "Attach game data to exe" option to General Settings. This lets you to package game data separately from the game.exe (only important on Windows at the moment).
- Deprecated "Limit display mode to 16-bit" property in Runtime Setup as it's no longer used by the engine.
- Display aspect ratio in game resolution dialog.
- Implemented classic Color Picker dialog for the Color type values in the property grid, instead of the default one which does not allow user-defined colors.
- Improved tab switching performance for script windows.
- Editor will now enforce full game rebuild after upgrading an older project, this ensures that all scripts are recompiled with the new version rules.
- Fixed room lists in property editor were not updated after room number is changed.
- Fixed importing pre-3.* projects broken by incorrect assignment of "Game file name" property.
- Fixed importing Characters and GUI without sprites still created empty sprite folders.
- Fixed crash when exporting/importing Characters with no Normal View.
- Fixed translation compiler did not correctly save some of the escaped sequences, such as "\n".

Scripting:
- Implemented correct parsing of a "const string" function return type.
- Fixed implementing imported functions was forbidden in the room scripts.

Script API:
- Added GUI.Shown readonly property that tells whether GUI is active on screen. This is primarily for GUIs with "Popup At Y" style, because they hide themselves regardless of Visible property. Note that since 3.5.0 GUI.Visible only tells a script-set value.
- File.Open() now supports $CONFIGFILE$ tag which will try to open user config file for reading or writing regardless of where config is located on disk.
- Added System.SaveConfigToFile() which writes current engine settings to the user config file. Only the options that can be changed at runtime are written back at the moment.
- GetTranslation() now returns "const string" (was "string"). This is to prevent modifying returned string using old-style string functions, such as StrCat(), as this string may be allocated in the internal engine memory for its own use.

Engine:
- Support loading audio and video from data packages larger than 2 GB.
- Improved game data loading times by introducing buffered file stream. Initial tests showed 3-4 times faster file reading.
- Improved game perfomance by not reupdating all of the GUIs each time anything changes, instead only affected GUI will be updated each time.
- Some improvement to general script perfomance.
- Some improvement to script Dictionary and Set types perfomance.
- Room Object's Graphic property now can be assigned a sprite with index over 32767 and up to 65535. This restriction is due to internal data format, which cannot be fully fixed without breaking compatibility with plugin API. This may still be worked around by assigning a View, as View's frames may contain sprites of any index available.
- Similarily, Object's View, Loop and Frame can now be assigned a value over 32767 and up to 65535; not that this was ever an issue...
- Removed arbitrary limit of 1000000 dynamic array elements (now supports over 2 billion).
- Dialogs with no enabled options left will be now stopped, instead of raising script error.
- Engine will not longer quit the game when failing to write a save, but simply display an error on screen (...why this was a thing in the first place?!).
- When restoring a save engine will now try to match game pack by GUID rather than using exe/pack name. This resolves potential problems when game package may have different name in distribution to another system. Also makes saves in multi-game collections more reliable.
- In Debug game mode allow to toggle infinite FPS mode (prior it could not be turned off).
- Expanded text parser error messages for easier debugging.
- Adjusted all the command-line options to have consistent prefix convention, where all full-name options must be preceded by double-dash, and one-letter options by single dash.
- Added "--localuserconf" command and similar global config option which tells engine to read and write user config in the game's directory rather than using standard platform path. Game dir must be writeable for this to work.
- Added "--conf" command which forces engine to read only explicit config file on startup.
- Added "--user-data-dir" and "--shared-data-dir" commands for setting save game directory and shared app data directory from command line (this corresponds to existing options in config).
- Fully configurable log output (in both game config and command line) allows to set up which message types and groups are printed by which output methods (sinks), including: file, system console, in-game console. "warnings.log" is now created only if file log was not requested by user.
- Added "--log-" set of command line options for setting up log output.
- Added "--tell-filepath" option for printing known engine's and game's file locations.
- Added "--tell-gameproperties" option for printing some of the game's general settings.
More information on log config and --tell commands currently may be found in following text file: OPTIONS.md
This has to be added to the manual eventually.
- Support proper lookup for Allegro 4 library resources (such as its own config and digital MIDI patches) in the game directory.
- Engine will no longer precreate directories for common files: saves, user config, shared files and so forth, - before actually having to write these. This ensures that no new directories are created on your disk without actual need. Also this fixed a problem that could happen if someone deleted e.g. a game's save directory while game was running.
- Fixed running game from another directory by passing its relative filename as command-line argument: in this case engine was incorrectly using its own directory to search for external game data, opening files for reading by script command, and so on.
- Fixed some of the engine's own hotkeys (such windowed/fullscreen mode toggle) not working during certain skippable game states.
- Fixed overlay was set to wrong position if it were using TextWindow gui and either its text or X, Y properties got changed.
- Fixed crash occuring when the speech is using text window gui with zero Padding and the speech text is an empty line.
- Fixed characters and room objects were not updating their looks if their current graphic was a Dynamic Sprite, and that sprite was modified with ChangeCanvasSize, CopyTransparencyMask, Crop, Flip, Resize, Rotate or Tint function.
- Fixed Views' frames keeping reference to deleted Dynamic Sprites causing crashes. Now they will be reset to dummy sprite 0 for safety.
- Fixed engine crash when button's graphic is set to sprite out of range.
- Fixed animated cursor's normal graphic reappearing in between animation frames if mouse mode is being repeatedly reassigned, for example in rep-exec script.
- Fixed certain interactions did not work with GUI if it was made fully transparent.
- Fixed ListBox.FillSaveGameList() search pattern, it included files which contain save filename pattern but do not exactly match; for example: "agssave.001_".
- Fixed engine was ignoring audio files in game directory when running games which use old audio system.
- Fixed crash in Direct3D and OpenGL renderers that occured if game uses a plugin that performs software drawing on screen, and one of the rooms is smaller than the game's resolution.
- Fixed Direct3D was assigning wrong fullscreen refresh rate sometimes, slowing alt-tabbing.
- Fixed "--test" mode was lost upon restoring a save.

Engine Plugin API:
- Added IAGSEngine::GetRenderStageDesc() function which returns current render stage parameters. As of this version these parameters include 3 transformation matrixes, allowing any 3D render plugin to stay compliant to engine's scene rendering.

Compatibility:
- Fixed engine was trying to read unnecessary data when loading pre-2.72 games.
- Fixed "upscale" mode for old games (was broken in 3.5.0). Also engine will now try to detect if "upscale" mode wanted by reading old config options (if they are present).
- Fixed GUI.Visible not returning expected values for GUIs with "Popup At Y" style in pre-3.5.0 games, breaking some older games logic.
- Fixed potential buffer overflow when reading pre-3.1.0 games with old dialog script texts.
- Fixed engine was applying player's position too early when ChangeRoom was called for 2.72 and earlier games, which could result in wrong placement in the new room if the character was walking right before the transition.

Android:
- Corrected game scanning in AGS launcher, now it will work consistently with the desktop ports, and detect any compatible game data files named "*.ags" or "*.exe".

OSX:
- When looking for game files engine will no longer use hardcoded filename, will search for any compatible pack file instead.

Windows:
- Windows version of the engine now reads global configuration file. It is looked up in "%USERPROFILE%/Saved Games/Adventure Game Studio/acsetup.cfg"
- Default log file location is now also in "%USERPROFILE%/Saved Games/Adventure Game Studio".
- Added "--no-message-box" command line option to hide message boxes when alerts are raised. These messages will be still printed to log (if one is enabled).
- Added "--console-attach" command line option to try attach to the parent process's console. This is useful if you run game from command line and want to see engine's log in the console.

WinSetup:
- Fixed changing fullscreen mode from "use current desktop" to explicit resolution on save.







Thanks to everyone who contributed to and tested this version!

[Download AGS 3.5.1 installer]

AGS 3.5.1 - Patch 17

Full release number: 3.5.1.24

Download AGS 3.5.1 installer

Download AGS 3.5.1 as a .zip archive

For Editor

Spoiler

VC 2015 redistributable needed for AGS Editor on Windows

Download Dark UI Theme for the editor

[close]

For Android

Spoiler

Android launcher (APK signed with Debug key), suitable for running any compatible AGS game

Native engine libraries, for making your own signed APKs

[close]

For Engine/Editor developers

Spoiler

AGS source code central repository

Debug symbols database (for analysing crash dumps)

[close]

Released: 16th January 2023

Previous stable version: AGS 3.5.0 P10 forum thread


This release is brought to you by:

- Alan v. Drake
- Crimson Wizard
- Donovan Watteau (fix for big-endian systems)
- eri0o
- fernewelten (fixes)
- James Duong (implemented "--console-attach" option for Windows)
- Morgan Willcock
- Nick Sonneveld
- rofl0r
- Pablo Navarro (fixes)
- Thierry Crozat (bug fixing)
- vga256 (bug fixing)



Summary

3.5.1 is a minor update after 3.5.0, which contains mostly utility additions, fixes and perfomance improvements.

Changes in the Patch 17:

Editor:
- Fixed GUI.Visible property was resetting to false when PopupStyle is switched to Modal.

Engine:
- Performance improvement in Direct3D/OpenGL renderers, related to plugins which subscribe to render events.
- Fixed renderer error occuring if room background frames are of different sizes.
- Fixed software renderer may have an unpainted black line at the bottom, if there's a GUI or Overlay positioned partially offscreen.
- Fixed GUI buttons could retain mouse-over pic after interface is disabled then enabled (this is a regression since recent patch).
- Fixed crash occuring when user creates too many Overlays in script; will report a scripting error instead.
- Fixed memory leak occuring when the TTF font is drawn partially outside the DrawingSurface.
- Fixed Parser.Said() could lead to a program crash in case there are space-separated words following the comma (e.g. "climb,get in bed").
- Fixed crash occuring if a plugin tried to call SetVirtualScreen().

Plugins:
- Fixed SnowRain plugin drawing particles only in 320x200 bounds.


Changes in the Patch 16:

Editor:
- Fixed autocomplete crashing the editor if there was an import declared with type and variable having identical names, and user tries to type that variable's name and a dot to access its members.
- Fixed newly created Views taking free IDs in the middle of the list in random order instead of a straight one (after you previously deleted some Views).

Engine:
- Added missing "DrawSprite" function for "agsblend" plugin stubs.
- Fixed loading pre-3.5.0 games on big endian systems.
- Fixed GUI buttons not displaying the mouse-over image if the interface state was toggled to enabled state while the mouse was over the button.

Updated the manual with certain fixes and corrected examples of using Camera and Viewport structs.


Changes in the Patch 15:

Editor:
- Fixed crash that could occur when changing View's ID to an unused number in the middle.
- Fixed comments and string literals were styled incorrectly in dialog scripts.
- Fixed unterminated string literals in script were not considered as errors when processing scripts for translation update and autonumbering of speech lines, leading to wrong results.
- Fixed Editor was updating translation file even if errors were found while scanning the scripts, which could cause a TRS corruption.
- Fixed Editor could overwrite changes done manually to TRS while the editor is open and if you run a translation update right after.
- Fixed potential program crash on exit in case an editor's plugin has mistakes in "shutdown" callback. Instead editor will report a component's error, but still close properly after.

Script API:
- Removed a rule that Viewport and Camera with ID 0 can't be deleted.


Changes in the Patch 14:

Editor:
- Do not error when compiling a 256 colors game if Direct3D or OpenGL are selected as a default graphics driver (display a warning instead).
- Fixed crash when trying to import pre-2.60 game projects.


Changes in the Patch 13:

Engine:
- Fixed room object does not update its texture if it had a dynamic sprite assigned to it, and that sprite was unassigned, modified or recreated with same ID, and then reassigned again, - all within the same game frame.
- Fixed normal font renderer is not reinitialized correctly in the engine if a plugin uses IAGSEngine::ReplaceFontRenderer(), passing original renderer's pointer (which it received from the previous ReplaceFontRenderer call).


Changes in the Patch 12:

Engine:
- Fixed GUI textual controls don't redraw when the game translation changes until player clicks on GUI (regression since previous 3.5.1 updates).
- Fixed multitasking mode persisting if the game was switched from windowed to fullscreen mode (even though it's not supposed to work in fullscreen).


Changes in the Patch 11:

Editor:
- Fixed batch sprite export with "Set exported file as sprite source" option was assigning new source paths without file extension.

Engine:
- Perfomance fix: GUIs changing Transparency or Visible state should not redraw their surface.

Compatibility:
- Allow AudioClip.Play to to place clips on a crossfade channel, which is normally unaccessible from script. This prevents errors in some games that relied on this behavior.


Changes in the Patch 10:

Engine:
- Fixed crash when visible viewport does not have any linked camera.
- Fixed ListBox.FillSaveGameList() may include save slots with negative slot number (e.g. when the save file has "*.-01" extension).
- Fixed potential crash after failed RunAGSGame() call.
- Fixed search for the game data by GUID when restoring a save belonging to another game;
  this was implemented in 3.5.1, but appeared to not work correctly.


Changes in the Patch 9:

Editor:
- Removed restriction on max dialog topics in the project. The dialog limit in the engine was removed in 3.4.1, but remained in the Editor by oversight.
- Fixed Audio Clip items in the project tree not displaying their IDs right after being renamed.

Compiler:
- Fixed crash occuring when compiler tries to report "Already referenced name as import" error.

Engine:
- Added "--translation" and "--no-translation" command-line arguments.


Changes in the Patch 8:

Engine:
- Clearer error messages for Get/SetProperty functions.
- Fixed PlayFlic() command fails to start the video (regression in 3.5.1).
- Fixed DrawingSurface.DrawSurface() not applying transparency parameter correctly if the drawn surface has alpha channel.
- Fixed OVERHOTSPOT is not updated immediately when character's name changes while cursor is above that character.

Templates:
- In BASS template fixed right click not dropping currently selected item if cursor was hovering over another item.


Changes in the Patch 7:

Editor:
- Added "Layout -> Reset to Defaults" menu command.
- Editor will now reset panel layout to default state if loading layout fail for any reason.
- Default config is now saved also when the game is run in debug mode (F5). This ensures that the test run is using the latest Default Setup, if the user's config has not been created yet.
- Editor will now display an error if user tried to reserve too many channels for audio types.
- Fixed Editor failing to start if user preferences file is corrupted.
- Fixed "Use old-style custom dialog options API" was not set when importing pre-3.4.0 projects.
- Fixed comboboxes' drop-down arrows were not painted with the right color from a color theme.

Engine:
- Fixed program crash occuring if the game reserved too many channels for audio types.
- Fixed potential crash occuring when player loads a save made in a multi-frame room, but the room was since edited and no longer has as many frames.
- Fixed character may have incorrect Frame (property) values while turning.


Changes in the Patch 6:

Editor:
- Added line numbers in the dialog script editor.
- Fixed Dialog script loosing changes if the pane is closed or redocked.
- Fixed controls arrangement on the Dialog pane getting broken when it's redocked.

Engine:
- Fixed filepaths in scripts that have backslashes ('\') fail on non-Windows systems.
  All the (script) File functions will now convert backslashes in filepaths into forward slashes for compatibility.
- Fixed engine was still creating standard directories for game saves and data, even if user provided the custom paths for these.
- Fixed TextBox control crashing the game if it's empty and player presses Backspace.
- Fixed controls on a fully transparent GUI were not interactive (this is an original AGS behavior, which was unintentionally changed in 3.5.0 by mistake).

Compatibility:
- When running 3.5.0 games, treat fully transparent GUI as non-interactable.
  In AGS transparent GUIs may be still interacted with, but 3.5.0 introduced an unintentional (and undocumented) change to this, which was reverted in 3.5.1.

Android:
- Support global engine's config file when the game is run from the Launcher: it's located in the AGS games' parent directory, same place where android.cfg is.

WinSetup:
- Added "Custom game shared data path" to complement "Custom save path" option.


Changes in the Patch 5:

Contained no changes and was a formal re-release with only fixed program build instructions for Linux.


Changes in the Patch 4:

Editor:
- Fixed swapping of inventory item's numeric ID could lead to errors.
- Fixed crash when importing pre-3.* games with multiple script modules.
- Renamed "Enforce object-based scripting" setting to "Enforce post-2.62 scripting". This is for clarity.

Compiler:
- Fixed potential memory corruption when user script reaches max nested if/else blocks.

Engine:
- Also tell module name and approximate source line when reporting script import errors for the variables and local functions.


Changes in the Patch 3:

Editor:
- Fixed sprite file over 2 GB could not be loaded (regression since the last patch).

Engine:
- Further improvement to GUI perfomance: don't redraw GUI when the mouse cursor is hovering over or interacting with controls not leading to an actual visual change.
- Fixed ListBox items could become unaccessible if its font or height is changed leading to a disabled scrollbar.


Changes in the Patch 2:

Engine:
- Fixed speech lipsync getting disabled after loading another game with RunAGSGame().
- Fixed MOD/XM clips fail to play (regression).
- Fixed certain OGV videos fail to play (regression).
- Fixed software renderer was not updating game screen correctly when running a game with legacy "letterboxed" feature (regression).


Changes in the Patch 1:

Editor:
- Fixed script compiler sometimes was not specifying actual Dialog number when reporting errors in the dialog scripts.

Engine:
- Fixed Game.TranslationFilename always returning empty string (regression).
- Fixed GUI controls which were toggled from disabled to enabled state not responding to the mouse clicks until the mouse is moved (regression).
- Fixed OpenGL did not apply a Linear filter when "Render sprites in screen resolution" option is off.


What is new in 3.5.1

Editor:
- Added "Attach game data to exe" option to General Settings. This lets you to package game data separately from the game.exe (only important on Windows at the moment).
- Deprecated "Limit display mode to 16-bit" property in Runtime Setup as it's no longer used by the engine.
- Display aspect ratio in game resolution dialog.
- Implemented classic Color Picker dialog for the Color type values in the property grid, instead of the default one which does not allow user-defined colors.
- Improved tab switching performance for script windows.
- Editor will now enforce full game rebuild after upgrading an older project, this ensures that all scripts are recompiled with the new version rules.
- Fixed room lists in property editor were not updated after room number is changed.
- Fixed importing pre-3.* projects broken by incorrect assignment of "Game file name" property.
- Fixed importing Characters and GUI without sprites still created empty sprite folders.
- Fixed crash when exporting/importing Characters with no Normal View.
- Fixed translation compiler did not correctly save some of the escaped sequences, such as "\n".

Scripting:
- Implemented correct parsing of a "const string" function return type.
- Fixed implementing imported functions was forbidden in the room scripts.

Script API:
- Added GUI.Shown readonly property that tells whether GUI is active on screen. This is primarily for GUIs with "Popup At Y" style, because they hide themselves regardless of Visible property. Note that since 3.5.0 GUI.Visible only tells a script-set value.
- File.Open() now supports $CONFIGFILE$ tag which will try to open user config file for reading or writing regardless of where config is located on disk.
- Added System.SaveConfigToFile() which writes current engine settings to the user config file. Only the options that can be changed at runtime are written back at the moment.
- GetTranslation() now returns "const string" (was "string"). This is to prevent modifying returned string using old-style string functions, such as StrCat(), as this string may be allocated in the internal engine memory for its own use.

Engine:
- Support loading audio and video from data packages larger than 2 GB.
- Improved game data loading times by introducing buffered file stream. Initial tests showed 3-4 times faster file reading.
- Improved game perfomance by not reupdating all of the GUIs each time anything changes, instead only affected GUI will be updated each time.
- Some improvement to general script perfomance.
- Some improvement to script Dictionary and Set types perfomance.
- Room Object's Graphic property now can be assigned a sprite with index over 32767 and up to 65535. This restriction is due to internal data format, which cannot be fully fixed without breaking compatibility with plugin API. This may still be worked around by assigning a View, as View's frames may contain sprites of any index available.
- Similarily, Object's View, Loop and Frame can now be assigned a value over 32767 and up to 65535; not that this was ever an issue...
- Removed arbitrary limit of 1000000 dynamic array elements (now supports over 2 billion).
- Dialogs with no enabled options left will be now stopped, instead of raising script error.
- Engine will not longer quit the game when failing to write a save, but simply display an error on screen (...why this was a thing in the first place?!).
- When restoring a save engine will now try to match game pack by GUID rather than using exe/pack name. This resolves potential problems when game package may have different name in distribution to another system. Also makes saves in multi-game collections more reliable.
- In Debug game mode allow to toggle infinite FPS mode (prior it could not be turned off).
- Expanded text parser error messages for easier debugging.
- Adjusted all the command-line options to have consistent prefix convention, where all full-name options must be preceded by double-dash, and one-letter options by single dash.
- Added "--localuserconf" command and similar global config option which tells engine to read and write user config in the game's directory rather than using standard platform path. Game dir must be writeable for this to work.
- Added "--conf" command which forces engine to read only explicit config file on startup.
- Added "--user-data-dir" and "--shared-data-dir" commands for setting save game directory and shared app data directory from command line (this corresponds to existing options in config).
- Fully configurable log output (in both game config and command line) allows to set up which message types and groups are printed by which output methods (sinks), including: file, system console, in-game console. "warnings.log" is now created only if file log was not requested by user.
- Added "--log-" set of command line options for setting up log output.
- Added "--tell-filepath" option for printing known engine's and game's file locations.
- Added "--tell-gameproperties" option for printing some of the game's general settings.
More information on log config and --tell commands currently may be found in following text file: OPTIONS.md
This has to be added to the manual eventually.
- Support proper lookup for Allegro 4 library resources (such as its own config and digital MIDI patches) in the game directory.
- Engine will no longer precreate directories for common files: saves, user config, shared files and so forth, - before actually having to write these. This ensures that no new directories are created on your disk without actual need. Also this fixed a problem that could happen if someone deleted e.g. a game's save directory while game was running.
- Fixed running game from another directory by passing its relative filename as command-line argument: in this case engine was incorrectly using its own directory to search for external game data, opening files for reading by script command, and so on.
- Fixed some of the engine's own hotkeys (such windowed/fullscreen mode toggle) not working during certain skippable game states.
- Fixed overlay was set to wrong position if it were using TextWindow gui and either its text or X, Y properties got changed.
- Fixed crash occuring when the speech is using text window gui with zero Padding and the speech text is an empty line.
- Fixed characters and room objects were not updating their looks if their current graphic was a Dynamic Sprite, and that sprite was modified with ChangeCanvasSize, CopyTransparencyMask, Crop, Flip, Resize, Rotate or Tint function.
- Fixed Views' frames keeping reference to deleted Dynamic Sprites causing crashes. Now they will be reset to dummy sprite 0 for safety.
- Fixed engine crash when button's graphic is set to sprite out of range.
- Fixed animated cursor's normal graphic reappearing in between animation frames if mouse mode is being repeatedly reassigned, for example in rep-exec script.
- Fixed certain interactions did not work with GUI if it was made fully transparent.
- Fixed ListBox.FillSaveGameList() search pattern, it included files which contain save filename pattern but do not exactly match; for example: "agssave.001_".
- Fixed engine was ignoring audio files in game directory when running games which use old audio system.
- Fixed crash in Direct3D and OpenGL renderers that occured if game uses a plugin that performs software drawing on screen, and one of the rooms is smaller than the game's resolution.
- Fixed Direct3D was assigning wrong fullscreen refresh rate sometimes, slowing alt-tabbing.
- Fixed "--test" mode was lost upon restoring a save.

Engine Plugin API:
- Added IAGSEngine::GetRenderStageDesc() function which returns current render stage parameters. As of this version these parameters include 3 transformation matrixes, allowing any 3D render plugin to stay compliant to engine's scene rendering.

Compatibility:
- Fixed engine was trying to read unnecessary data when loading pre-2.72 games.
- Fixed "upscale" mode for old games (was broken in 3.5.0). Also engine will now try to detect if "upscale" mode wanted by reading old config options (if they are present).
- Fixed GUI.Visible not returning expected values for GUIs with "Popup At Y" style in pre-3.5.0 games, breaking some older games logic.
- Fixed potential buffer overflow when reading pre-3.1.0 games with old dialog script texts.
- Fixed engine was applying player's position too early when ChangeRoom was called for 2.72 and earlier games, which could result in wrong placement in the new room if the character was walking right before the transition.

Android:
- Corrected game scanning in AGS launcher, now it will work consistently with the desktop ports, and detect any compatible game data files named "*.ags" or "*.exe".

OSX:
- When looking for game files engine will no longer use hardcoded filename, will search for any compatible pack file instead.

Windows:
- Windows version of the engine now reads global configuration file. It is looked up in "%USERPROFILE%/Saved Games/Adventure Game Studio/acsetup.cfg"
- Default log file location is now also in "%USERPROFILE%/Saved Games/Adventure Game Studio".
- Added "--no-message-box" command line option to hide message boxes when alerts are raised. These messages will be still printed to log (if one is enabled).
- Added "--console-attach" command line option to try attach to the parent process's console. This is useful if you run game from command line and want to see engine's log in the console.

WinSetup:
- Fixed changing fullscreen mode from "use current desktop" to explicit resolution on save.







Thanks to everyone who contributed to and tested this version!

I keep hitting a post limit of 30k characters when making Release posts, because I need to put download links, changelog (which may contain a lengthy list of items), and some overview, etc.

I guess the easiest workaround would be to make extra empty post(s) for backup, right after the first one. But in this case I forgot to add one.

Is it possible to somehow add an extra post in the middle, if I'm a local moderator?

Hmm, maybe I should be giving a link to changelog elsewhere instead.

[Download AGS 3.5.1 installer]

AGS 3.5.1 - Patch 16

Full release number: 3.5.1.23

Download AGS 3.5.1 installer

Download AGS 3.5.1 as a .zip archive

For Editor

Spoiler

VC 2015 redistributable needed for AGS Editor on Windows

Download Dark UI Theme for the editor

[close]

For Android

Spoiler

Android launcher (APK signed with Debug key), suitable for running any compatible AGS game

Native engine libraries, for making your own signed APKs

[close]

For Engine/Editor developers

Spoiler

AGS source code central repository

Debug symbols database (for analysing crash dumps)

[close]

Released: 2nd December 2022

Previous stable version: AGS 3.5.0 P10 forum thread


This release is brought to you by:

- Alan v. Drake
- Crimson Wizard
- Donovan Watteau (fix for big-endian systems)
- eri0o
- fernewelten (fixes)
- James Duong (implemented "--console-attach" option for Windows)
- Morgan Willcock
- Nick Sonneveld
- rofl0r
- Pablo Navarro (fixes)
- Thierry Crozat (bug fixing)
- vga256 (bug fixing)



Summary

3.5.1 is a minor update after 3.5.0, which contains mostly utility additions, fixes and perfomance improvements.

Changes in the Patch 16:

Editor:
- Fixed autocomplete crashing the editor if there was an import declared with type and variable having identical names, and user tries to type that variable's name and a dot to access its members.
- Fixed newly created Views taking free IDs in the middle of the list in random order instead of a straight one (after you previously deleted some Views).

Engine:
- Added missing "DrawSprite" function for "agsblend" plugin stubs.
- Fixed loading pre-3.5.0 games on big endian systems.
- Fixed GUI buttons not displaying the mouse-over image if the interface state was toggled to enabled state while the mouse was over the button.

Updated the manual with certain fixes and corrected examples of using Camera and Viewport structs.


Changes in the Patch 15:

Editor:
- Fixed crash that could occur when changing View's ID to an unused number in the middle.
- Fixed comments and string literals were styled incorrectly in dialog scripts.
- Fixed unterminated string literals in script were not considered as errors when processing scripts for translation update and autonumbering of speech lines, leading to wrong results.
- Fixed Editor was updating translation file even if errors were found while scanning the scripts, which could cause a TRS corruption.
- Fixed Editor could overwrite changes done manually to TRS while the editor is open and if you run a translation update right after.
- Fixed potential program crash on exit in case an editor's plugin has mistakes in "shutdown" callback. Instead editor will report a component's error, but still close properly after.

Script API:
- Removed a rule that Viewport and Camera with ID 0 can't be deleted.


Changes in the Patch 14:

Editor:
- Do not error when compiling a 256 colors game if Direct3D or OpenGL are selected as a default graphics driver (display a warning instead).
- Fixed crash when trying to import pre-2.60 game projects.


Changes in the Patch 13:

Engine:
- Fixed room object does not update its texture if it had a dynamic sprite assigned to it, and that sprite was unassigned, modified or recreated with same ID, and then reassigned again, - all within the same game frame.
- Fixed normal font renderer is not reinitialized correctly in the engine if a plugin uses IAGSEngine::ReplaceFontRenderer(), passing original renderer's pointer (which it received from the previous ReplaceFontRenderer call).


Changes in the Patch 12:

Engine:
- Fixed GUI textual controls don't redraw when the game translation changes until player clicks on GUI (regression since previous 3.5.1 updates).
- Fixed multitasking mode persisting if the game was switched from windowed to fullscreen mode (even though it's not supposed to work in fullscreen).


Changes in the Patch 11:

Editor:
- Fixed batch sprite export with "Set exported file as sprite source" option was assigning new source paths without file extension.

Engine:
- Perfomance fix: GUIs changing Transparency or Visible state should not redraw their surface.

Compatibility:
- Allow AudioClip.Play to to place clips on a crossfade channel, which is normally unaccessible from script. This prevents errors in some games that relied on this behavior.


Changes in the Patch 10:

Engine:
- Fixed crash when visible viewport does not have any linked camera.
- Fixed ListBox.FillSaveGameList() may include save slots with negative slot number (e.g. when the save file has "*.-01" extension).
- Fixed potential crash after failed RunAGSGame() call.
- Fixed search for the game data by GUID when restoring a save belonging to another game;
  this was implemented in 3.5.1, but appeared to not work correctly.


Changes in the Patch 9:

Editor:
- Removed restriction on max dialog topics in the project. The dialog limit in the engine was removed in 3.4.1, but remained in the Editor by oversight.
- Fixed Audio Clip items in the project tree not displaying their IDs right after being renamed.

Compiler:
- Fixed crash occuring when compiler tries to report "Already referenced name as import" error.

Engine:
- Added "--translation" and "--no-translation" command-line arguments.


Changes in the Patch 8:

Engine:
- Clearer error messages for Get/SetProperty functions.
- Fixed PlayFlic() command fails to start the video (regression in 3.5.1).
- Fixed DrawingSurface.DrawSurface() not applying transparency parameter correctly if the drawn surface has alpha channel.
- Fixed OVERHOTSPOT is not updated immediately when character's name changes while cursor is above that character.

Templates:
- In BASS template fixed right click not dropping currently selected item if cursor was hovering over another item.


Changes in the Patch 7:

Editor:
- Added "Layout -> Reset to Defaults" menu command.
- Editor will now reset panel layout to default state if loading layout fail for any reason.
- Default config is now saved also when the game is run in debug mode (F5). This ensures that the test run is using the latest Default Setup, if the user's config has not been created yet.
- Editor will now display an error if user tried to reserve too many channels for audio types.
- Fixed Editor failing to start if user preferences file is corrupted.
- Fixed "Use old-style custom dialog options API" was not set when importing pre-3.4.0 projects.
- Fixed comboboxes' drop-down arrows were not painted with the right color from a color theme.

Engine:
- Fixed program crash occuring if the game reserved too many channels for audio types.
- Fixed potential crash occuring when player loads a save made in a multi-frame room, but the room was since edited and no longer has as many frames.
- Fixed character may have incorrect Frame (property) values while turning.


Changes in the Patch 6:

Editor:
- Added line numbers in the dialog script editor.
- Fixed Dialog script loosing changes if the pane is closed or redocked.
- Fixed controls arrangement on the Dialog pane getting broken when it's redocked.

Engine:
- Fixed filepaths in scripts that have backslashes ('\') fail on non-Windows systems.
  All the (script) File functions will now convert backslashes in filepaths into forward slashes for compatibility.
- Fixed engine was still creating standard directories for game saves and data, even if user provided the custom paths for these.
- Fixed TextBox control crashing the game if it's empty and player presses Backspace.
- Fixed controls on a fully transparent GUI were not interactive (this is an original AGS behavior, which was unintentionally changed in 3.5.0 by mistake).

Compatibility:
- When running 3.5.0 games, treat fully transparent GUI as non-interactable.
  In AGS transparent GUIs may be still interacted with, but 3.5.0 introduced an unintentional (and undocumented) change to this, which was reverted in 3.5.1.

Android:
- Support global engine's config file when the game is run from the Launcher: it's located in the AGS games' parent directory, same place where android.cfg is.

WinSetup:
- Added "Custom game shared data path" to complement "Custom save path" option.


Changes in the Patch 5:

Contained no changes and was a formal re-release with only fixed program build instructions for Linux.


Changes in the Patch 4:

Editor:
- Fixed swapping of inventory item's numeric ID could lead to errors.
- Fixed crash when importing pre-3.* games with multiple script modules.
- Renamed "Enforce object-based scripting" setting to "Enforce post-2.62 scripting". This is for clarity.

Compiler:
- Fixed potential memory corruption when user script reaches max nested if/else blocks.

Engine:
- Also tell module name and approximate source line when reporting script import errors for the variables and local functions.


Changes in the Patch 3:

Editor:
- Fixed sprite file over 2 GB could not be loaded (regression since the last patch).

Engine:
- Further improvement to GUI perfomance: don't redraw GUI when the mouse cursor is hovering over or interacting with controls not leading to an actual visual change.
- Fixed ListBox items could become unaccessible if its font or height is changed leading to a disabled scrollbar.


Changes in the Patch 2:

Engine:
- Fixed speech lipsync getting disabled after loading another game with RunAGSGame().
- Fixed MOD/XM clips fail to play (regression).
- Fixed certain OGV videos fail to play (regression).
- Fixed software renderer was not updating game screen correctly when running a game with legacy "letterboxed" feature (regression).


Changes in the Patch 1:

Editor:
- Fixed script compiler sometimes was not specifying actual Dialog number when reporting errors in the dialog scripts.

Engine:
- Fixed Game.TranslationFilename always returning empty string (regression).
- Fixed GUI controls which were toggled from disabled to enabled state not responding to the mouse clicks until the mouse is moved (regression).
- Fixed OpenGL did not apply a Linear filter when "Render sprites in screen resolution" option is off.


What is new in 3.5.1

Editor:
- Added "Attach game data to exe" option to General Settings. This lets you to package game data separately from the game.exe (only important on Windows at the moment).
- Deprecated "Limit display mode to 16-bit" property in Runtime Setup as it's no longer used by the engine.
- Display aspect ratio in game resolution dialog.
- Implemented classic Color Picker dialog for the Color type values in the property grid, instead of the default one which does not allow user-defined colors.
- Improved tab switching performance for script windows.
- Editor will now enforce full game rebuild after upgrading an older project, this ensures that all scripts are recompiled with the new version rules.
- Fixed room lists in property editor were not updated after room number is changed.
- Fixed importing pre-3.* projects broken by incorrect assignment of "Game file name" property.
- Fixed importing Characters and GUI without sprites still created empty sprite folders.
- Fixed crash when exporting/importing Characters with no Normal View.
- Fixed translation compiler did not correctly save some of the escaped sequences, such as "\n".

Scripting:
- Implemented correct parsing of a "const string" function return type.
- Fixed implementing imported functions was forbidden in the room scripts.

Script API:
- Added GUI.Shown readonly property that tells whether GUI is active on screen. This is primarily for GUIs with "Popup At Y" style, because they hide themselves regardless of Visible property. Note that since 3.5.0 GUI.Visible only tells a script-set value.
- File.Open() now supports $CONFIGFILE$ tag which will try to open user config file for reading or writing regardless of where config is located on disk.
- Added System.SaveConfigToFile() which writes current engine settings to the user config file. Only the options that can be changed at runtime are written back at the moment.
- GetTranslation() now returns "const string" (was "string"). This is to prevent modifying returned string using old-style string functions, such as StrCat(), as this string may be allocated in the internal engine memory for its own use.

Engine:
- Support loading audio and video from data packages larger than 2 GB.
- Improved game data loading times by introducing buffered file stream. Initial tests showed 3-4 times faster file reading.
- Improved game perfomance by not reupdating all of the GUIs each time anything changes, instead only affected GUI will be updated each time.
- Some improvement to general script perfomance.
- Some improvement to script Dictionary and Set types perfomance.
- Room Object's Graphic property now can be assigned a sprite with index over 32767 and up to 65535. This restriction is due to internal data format, which cannot be fully fixed without breaking compatibility with plugin API. This may still be worked around by assigning a View, as View's frames may contain sprites of any index available.
- Similarily, Object's View, Loop and Frame can now be assigned a value over 32767 and up to 65535; not that this was ever an issue...
- Removed arbitrary limit of 1000000 dynamic array elements (now supports over 2 billion).
- Dialogs with no enabled options left will be now stopped, instead of raising script error.
- Engine will not longer quit the game when failing to write a save, but simply display an error on screen (...why this was a thing in the first place?!).
- When restoring a save engine will now try to match game pack by GUID rather than using exe/pack name. This resolves potential problems when game package may have different name in distribution to another system. Also makes saves in multi-game collections more reliable.
- In Debug game mode allow to toggle infinite FPS mode (prior it could not be turned off).
- Expanded text parser error messages for easier debugging.
- Adjusted all the command-line options to have consistent prefix convention, where all full-name options must be preceded by double-dash, and one-letter options by single dash.
- Added "--localuserconf" command and similar global config option which tells engine to read and write user config in the game's directory rather than using standard platform path. Game dir must be writeable for this to work.
- Added "--conf" command which forces engine to read only explicit config file on startup.
- Added "--user-data-dir" and "--shared-data-dir" commands for setting save game directory and shared app data directory from command line (this corresponds to existing options in config).
- Fully configurable log output (in both game config and command line) allows to set up which message types and groups are printed by which output methods (sinks), including: file, system console, in-game console. "warnings.log" is now created only if file log was not requested by user.
- Added "--log-" set of command line options for setting up log output.
- Added "--tell-filepath" option for printing known engine's and game's file locations.
- Added "--tell-gameproperties" option for printing some of the game's general settings.
More information on log config and --tell commands currently may be found in following text file: OPTIONS.md
This has to be added to the manual eventually.
- Support proper lookup for Allegro 4 library resources (such as its own config and digital MIDI patches) in the game directory.
- Engine will no longer precreate directories for common files: saves, user config, shared files and so forth, - before actually having to write these. This ensures that no new directories are created on your disk without actual need. Also this fixed a problem that could happen if someone deleted e.g. a game's save directory while game was running.
- Fixed running game from another directory by passing its relative filename as command-line argument: in this case engine was incorrectly using its own directory to search for external game data, opening files for reading by script command, and so on.
- Fixed some of the engine's own hotkeys (such windowed/fullscreen mode toggle) not working during certain skippable game states.
- Fixed overlay was set to wrong position if it were using TextWindow gui and either its text or X, Y properties got changed.
- Fixed crash occuring when the speech is using text window gui with zero Padding and the speech text is an empty line.
- Fixed characters and room objects were not updating their looks if their current graphic was a Dynamic Sprite, and that sprite was modified with ChangeCanvasSize, CopyTransparencyMask, Crop, Flip, Resize, Rotate or Tint function.
- Fixed Views' frames keeping reference to deleted Dynamic Sprites causing crashes. Now they will be reset to dummy sprite 0 for safety.
- Fixed engine crash when button's graphic is set to sprite out of range.
- Fixed animated cursor's normal graphic reappearing in between animation frames if mouse mode is being repeatedly reassigned, for example in rep-exec script.
- Fixed certain interactions did not work with GUI if it was made fully transparent.
- Fixed ListBox.FillSaveGameList() search pattern, it included files which contain save filename pattern but do not exactly match; for example: "agssave.001_".
- Fixed engine was ignoring audio files in game directory when running games which use old audio system.
- Fixed crash in Direct3D and OpenGL renderers that occured if game uses a plugin that performs software drawing on screen, and one of the rooms is smaller than the game's resolution.
- Fixed Direct3D was assigning wrong fullscreen refresh rate sometimes, slowing alt-tabbing.
- Fixed "--test" mode was lost upon restoring a save.

Engine Plugin API:
- Added IAGSEngine::GetRenderStageDesc() function which returns current render stage parameters. As of this version these parameters include 3 transformation matrixes, allowing any 3D render plugin to stay compliant to engine's scene rendering.

Compatibility:
- Fixed engine was trying to read unnecessary data when loading pre-2.72 games.
- Fixed "upscale" mode for old games (was broken in 3.5.0). Also engine will now try to detect if "upscale" mode wanted by reading old config options (if they are present).
- Fixed GUI.Visible not returning expected values for GUIs with "Popup At Y" style in pre-3.5.0 games, breaking some older games logic.
- Fixed potential buffer overflow when reading pre-3.1.0 games with old dialog script texts.
- Fixed engine was applying player's position too early when ChangeRoom was called for 2.72 and earlier games, which could result in wrong placement in the new room if the character was walking right before the transition.

Android:
- Corrected game scanning in AGS launcher, now it will work consistently with the desktop ports, and detect any compatible game data files named "*.ags" or "*.exe".

OSX:
- When looking for game files engine will no longer use hardcoded filename, will search for any compatible pack file instead.

Windows:
- Windows version of the engine now reads global configuration file. It is looked up in "%USERPROFILE%/Saved Games/Adventure Game Studio/acsetup.cfg"
- Default log file location is now also in "%USERPROFILE%/Saved Games/Adventure Game Studio".
- Added "--no-message-box" command line option to hide message boxes when alerts are raised. These messages will be still printed to log (if one is enabled).
- Added "--console-attach" command line option to try attach to the parent process's console. This is useful if you run game from command line and want to see engine's log in the console.

WinSetup:
- Fixed changing fullscreen mode from "use current desktop" to explicit resolution on save.







Thanks to everyone who contributed to and tested this version!

[Download AGS 3.6.0 RC installer]

AGS 3.6.0 - RC11

Full release number: 3.6.0.46

Download AGS 3.6.0 RC installer

Download AGS 3.6.0 RC as a .zip archive

For Editor

Spoiler

VC 2015 redistributable needed for AGS Editor on Windows

Download Color Themes for the Editor

[close]

For Android

Spoiler

AGS Player, suitable for running any compatible AGS game

NOTE: the Editor now includes Android build component letting you prepare your own games for Android

[close]

For Engine/Editor developers

Spoiler

AGS source code central repository

Debug symbols database (for analysing crash dumps)

[close]

Released: 25th March 2023

Previous stable version: AGS 3.5.1 P19 forum thread


This release is brought to you by:

- sonneveld (porting engine to SDL2)
- Alan v. Drake (improvements, fixes)
- Cameron Cawley [ccawley2011] (fixes, improvements to SpriteFont plugin)
- Crimson Wizard (stuff )
- Dominik Mierzejewski (fix)
- Donovan Watteau (fix)
- eri0o (updated Android port, Web port, Editor improvements, etc)
- fernewelten (new fonts outlining, improvements to script compiler, fixes)
- Francesco Ariis (fixes)
- Morgan Willcock (improving templates, help with CI)
- Pablo Navarro [panreyes] (fixes)
- ChamberOfFear (improvements)
- rofl0r (fixes, suggestions)
- Thierry Crozat (fixes, plugin update)
- vga256 (fixes)



What is new in 3.6.0

AGS 3.6.0 is another big change to AGS.
First of all, this release presents a SDL2-based engine. For about 2 decades AGS engine was based on Allegro 4 graphic library, which was discontinued somewhere in the early 2010-ies (only received few patches since). There was an intent to move either to Allegro 5 or SDL (1 or 2) since, but for various reasons this task was continuously postponed.
Secondly the Editor and Engine now have full Unicode support. This means that you may use any language whatsoever in scripts, object descriptions and custom properties, as well as translations; so long as you also provide proper unicode fonts.
Third, we finally have expanded a list of platforms that the Editor can build for: now this includes Android and Web (Emscripten) port.

For more information please make sure to read "Upgrading to AGS 3.6" topic in the manual: https://adventuregamestudio.github.io/ags-manual/UpgradeTo36.html


Common features:
- Full Unicode support for all game texts: game properties, scripts, translations, input.
  ASCII/ANSI mode is still working, for backwards compatibility. This may be configured in the game project.
- Extended sprite compression options: lossless storage optimization for 16- and 32-bit sprites; LZW compression option for sprites in addition to existing RLE compression.
- GUI controls may now be told to clip their contents, which means that nothing gets drawn outside of their borders (as defined by X, Y, Width, Height properties). The only exception is Sliders, which are more complicated.
- The historical TTF fonts' "fixup" that altered their height and vertical offset is now optional and works only if backwards compatible option is set.
- Max number of AudioChannels is now 16 (was 8).
- Removed game Cursors hard limit (was 20).
- Increased Room Objects limit to 256 (was 40).
- Discontinued "Windows Game Explorer" support in both Editor and Engine.

Editor:
- Editor requires .NET Framework 4.6 to run.
- Added Android build target support (requires "Android component" installed).
- Added Web/Emscripten build target support (requires "Web build component" installed).
- Expanded UI color theme format, support global color options and allow missing entries.
- Script editor works in unicode mode.
- Added "Text format" option in General Settings which lets switching between ASCII/ANSI and Unicode (UTF-8) modes. This defines which format the game texts will be written in, when saving the game project and compiling the game.
- Added "Use old-style keyboard handling" option to the General Settings, which lets select between classic key press handling and new one meant for unicode chars support in scripts.
- Added "Touch to Mouse Emulation", "Touch to Mouse motion mode" and "Display FPS on Screen" to Default Setup. Removed few deprecated options.
- Supports compiling UTF-8 translations. TRS file now has "Encoding" setting that tells how to interpret this TRS text.
- Added support for building multiple speech voxes, by taking files from the Speech subfolders.
- Added support for adding custom files into the game package. This is done by assigning a list of directories to "Package custom data folder" option in General Settings.
- Editor now copies a acsetup.cfg file from the project's root folder (if one is provided by) as a base for generating default config file. Settings from Default Setup will be written over, but other found options won't be removed.
- Added "Sprite file compression" option in General Settings, replacing "Compress the sprite file" option. The new option allows a selection of compression algorithm used for sprites.
  Currently supported: None, RLE (old default compression) and LZW.
- Added "Enable sprite storage optimization" option to the General Settings, that permits the editor to repack sprites in a different storage format, reducing their disk size whenever possible.
  This option may be used alongside with the sprite compression. Note that this does not change how the sprites work in game.
- Added "GUI controls clip their contents" option to the General Settings.
- Added "TTF fonts height used in the game logic" option to the General Settings, that makes your game use real font's pixel height when arranging text and text-based UI elements, as opposed to the nominal font's size.
- Added "TTF font adjustment" property to Fonts, as well as to General Settings where it serves as a project default for the new fonts.
  This property lets you choose between "no changes" and backward compatible TTF fixup meant to keep fonts made for AGS displayed as they were meant to.
- In the "Import TTF" dialog added a choice to import the size closest to the given pixel height.
- Fonts now have Auto Outline Style and Auto Outline Thickness properties.
- Fonts now have a readonly Family Name field, that lets user see the original name of a font they've imported (if available).
- Added IdleDelay property to Characters that lets you set time needed to pass before IdleView is activated. This is equivalent to the Character.SetIdleView script function.
- Added Character.IdleAnimationDelay property to let setup idle view's animation speed.
- Added Cursor.AnimationDelay property to let setup cursor's animation speed.
- The TextWindow edges now have distinct names in the dropdown list of the property grid.
- Rooms created from a Blank template will now have default background of a game's resolution.
- When creating new room objects they will now have their script names set to some default value.
- Added Room.BackgroundAnimationEnabled property to let have disabled animation on room load.
- Editor will now create an empty sprite file if one is missing in the game project. Any existing sprite descriptions in the project will be kept, letting user to reimport these from sources.
- Added "File -> Restore all sprites from sources" menu command.
- Added "Apply" button on editor's Preferences dialog.
- In Preferences replaced "Import Color Theme" with a "Open Theme Folder", as a temporary solution for managing theme files.
- Select script editor's font in the editor's Preferences.
- Added "Help" option to the editor pane's tab context menu.
- Upgraded script editor to Scintilla 3.21.1 and ScintillaNET 3.6.3.
- Cursor's position in script is now displayed on the status bar.
- Dialog scripts now too can open help topics for keywords or script functions under cursor on F1.
- Added zoom controls for the Sprite Manager, Character, Cursor, Inventory and View panes.
- Sprites may now be imported by drag'n'drop into the Sprite manager.
- In sprite manager's context menu added command "Create source files for all sprites with missing external sources..."
- In sprite manager's context menu added (restored) command "Replace sprite using previous files".
  Also made "previous file" remembered consistently whenever a sprite is imported or replaced.
- In sprite manager's "export all" dialog added "skip if inside project's folder" option.
- In sprite manager's "export all" dialog added "reset tile settings" option.
- On the View pane the frames having set delay and linked sound will be now indicated with icons.
- Editor no longer errors and fails when opening a game project with some script files missing.
- Editor no longer errors on empty translations when compiling the game.
- Editor now exports values of the string type Custom Properties to translations.
- Editor no longer prevents exporting string arguments from Get/SetTextProperty calls to TRS file.
- Editor now cleanups spritefile on game load, identifying any data not referenced by the project and marking it for deletion.
- Fixed editor silently enabling all available Build Targets when upgrading a pre-3.4.0 project. This could be very inconvenient as there are several of them supported now.
- Fixed open folders in the Project Tree were collapsing whenever you create a new subfolder or change an object's name in properties.
- Fixed editor was not preventing from entering Character's and AudioClip's ScriptName too long for the engine to handle.
- Fixed Image and View properties in various objects were allowing negative values.
- Fixed some of the object previews (at least GUI) could crash if user entered a non-existing sprite's number as an Image property.
- Fixed editor displaying unhandled exception if the script which user is trying to open was missing. Instead it will now open a blank script.
- Fixed room editor was suggesting to save the modified room even if no changes were made.
- Fixed a recently imported sprite could be displayed incorrectly scaled up in the room editor for high-resolution games, if the "Allow relative asset resolutions" was enabled in General Settings, and the sprite 0 had "Resolution" property set to "Low".
- Fixed program crash occuring on sprite's import if failed to open a source file for any reason.
- Fixed View animation preview stopping at frame 100 (if loop contains over 100 frames).
- Fixed going to a "find all" result in dialog script did not highlight the found text, and sometimes did not scroll down to it.
- Fixed "Goto Definition" not working for Enums and Defines (macros).
- Fixed script autocomplete sometimes was not updated right after opening a script.
- Fixed script autocomplete for function calls was mistreating commas in strings and inline comments as if they were separating actual parameters.
- Fixed script autocomplete was not displaying members of extended structs if the parent struct was declared in another header.
- Fixed script autocomplete was not working for enum names.
- Fixed autocomplete crashing the editor if there was an import declared with type and variable having identical names, and user tries to type that variable's name and a dot to access its members.
- Fixed structs and enums were not highlighted if declared inside a script's body.
- Fixed in dialogs numbers inside names were incorrectly highlighted as numeric values.
- Fixed matching or mismatching braces were not highlighted consistently at all times in regular and dialog scripts.
- Fixed crash occuring when user was trying to set breakpoint on the very last line in script.
- Fixed few editor panes were not opening correct help topics in F1.
- (Possibly) fixed error message text in the runtime error popup could be drawn partially beyond the popup borders if the user's system has text scaling option enabled.

Script compiler:
- Support unicode character literals.
- Support using float literals when defining default values for function arguments.
- Support hexadecimal number literals (e.g. "0xABCDEF").
- Removed 500-characters line limit.

Script API:
- Expanded `on_key_press` callback, now supports two parameters: key code and key modifier flags.
- In the new key handling mode `on_key_press` is called for each actual key press;
  e.g. combinations like Ctrl+Z will result in two `on_key_press` calls, one with eKeyCtrlLeft and second with eKeyZ; added support for "NEW_KEYINPUT_API" macro in scripts.
- Implemented new `on_text_input(int ch)` callback which is called when the engine receives a printable character. This callback is essential for handling unicode chars in script.
- Similarily, expanded `dialog_options_key_press` with the third `mod` argument, and implemented `dialog_options_text_input` callback for receiving unicode chars during the custom dialog options state.
- Implemented `dialog_options_close` callback which is called when custom dialog options are removed from the screen. This allows to perform any required cleanup.
- Added eEventEnterRoomAfterFadein event for `on_event` callback, which corresponds to "enter after fade-in" room event.
- Added eKey constants for Shift, Control and Alt keys.
- Added eKeyMod enum for key modifiers constants.
- String.AppendChar(), ReplaceChar() functions and String.Chars[] property are now working with the unicode characters.
- String.Format("%c") specifier will now be able to print unicode characters.
- Extended Button.Animate() to have blocking style, direction and starting frame parameters, thus matching other Animate commands (of Character and Object).
- Extended all Animate() commands by adding "volume" parameter, that defines volume of the frame-linked sounds for the duration of this animation.
- Added Character.AnimationVolume, defining volume of the frame-linked sounds.
- Added Character.IdleAnimationDelay to let control idle view's animation speed.
- Character.Scaling is no longer limited by a range of 5-200 (now supports 1-32767).
- Hotspot.Name and Object.Name may now be set in script.
- Added Object.ManualScaling and Object.Scaling.
- Deprecated Object.IgnoreScaling (use Object.ManualScaling instead).
- Object.SetView default loop & frame values are now 0 (was -1 which retained loop and frame indexes from the previous view, often unexpected to the user).
- DrawingSurface.DrawImage() and DrawSurface() now support optional source rect coordinates.
- Added functions for getting DrawingSurface of room masks: GetDrawingSurfaceForWalkableArea(), GetDrawingSurfaceForWalkbehind(), Hotspot.GetDrawingSurface(), Region.GetDrawingSurface().
- Added new delay parameter to Mouse.ChangeModeView() to let control cursor's animation speed.
- Added Game.ChangeSpeechVox() and Game.SpeechVoxFilename, support switching the voice-over pack.
- Added Mouse.AutoLock property that toggles automatic mouse lock inside the game window.
- Added Room.Exists().
- Added System.Log().
- Added SkipWait() that skips any active Wait() function.
- Added WaitMouse() to complement existing Wait functions.
- Added InputType enum which defines input devices and lets create their sets as flags.
- Added WaitInput(), a more generic and extendable function that accepts a combination of flags telling which input types to wait for.
- All Wait* functions now may have infinite timeout if you pass a negative timeout parameter.
- All Wait* functions now return the reason they were skipped: a combination of InputType flag and a respective key or button code.
- Added GUIControl.Transparency property.
- Added Overlay.CreateRoomGraphical and CreateRoomTextual. Use these two functions to create "room overlays": that is - overlays that display a sprite inside the room, sorted among other room objects, characters and walk-behinds.
- Added readonly Overlay.InRoom property that tells if this is a room or screen overlay.
- Extended Overlay.CreateGraphical() with a new "clone" parameter that tells whether to assign a sprite index, or make a sprite's copy owned exclusively by this overlay.
  The former will save program memory but make overlay update if the sprite is edited later. The latter is meant primarily for backwards compatibility. Overlay.CreateRoomGraphical has the same param.
- Added Overlay.Graphic property that lets you change overlay's sprite after it's created.
- Added Overlay.Width and Height properties, that let you freely scale existing Overlay.
- Added readonly Overlay.GraphicWidth and GraphicHeight properties that let read original overlay's graphic size, as not all overlays hold a sprite reference (e.g. textual overlays).
- Added Overlay.Transparency property.
- Added Overlay.ZOrder property that lets you sort Overlays among themselves and other objects in the same "game layer": screen overlays are sorted among GUI, while room overlays are sorted among room objects, characters and walk-behinds.
- Added Speech.TextOverlay and Speech.PortraitOverlay for accessing blocking speech overlay and portrait overlay respectively.
- Added Game.BlockingWaitSkipped which tells the result of the last blocking wait skipping, also including result of the blocking speech skipping.
- SkipSpeechStyle now supports eSkipNone mode; when used it will disable any kind of skipping, such speech can be only skipped by a direct command from script.
- Extended Screen.ScreenToRoomPoint() with an optional "restrictToViewport" argument, which lets to choose whether tests over empty place result in conversion through the default viewport or a null pointer.
- Added AudioClip.PlayOnChannel().
- Added AudioChannel.Pause() and Resume() functions, and IsPaused property.
- Added AudioChannel.SeekMs(), complementing PositionMs (as the Seek() function interprets position differently depending on the audio format).
- PlayVideo() now supports an option to play both game's and video's audio track simultaneously.
- Added File.WriteRawInt() to complement ReadRawInt().
- File paths in script now support $DATA$ token, which tells to read files from the game package.
  This only works for read operations. Functions that support this token currently are: File.Open(), DynamicSprite.CreateFromFile(), ListBox.FillDirList().
- Debug(2, 0) command that displayed walkable areas is superceded by Debug(2, n), where "n" is a mask type: 0 - none, 1 - hotspots, 2 - walkbehinds, 3 - walkable areas, 4 - regions. This command also works as a toggle switch, calling it with the same mask index will turn it off.
- Debug(5, n) command that displayed character's walk paths now also works as a toggle switch.

Engine:
- New SDL2-based backend for graphics, audio and input.
- Hqx graphic filters discontinued (could be temporary).
- Windows-only DirectMedia video playback discontinued (could be temporary).
  Only OGG/OGV videos are kept supported at this point.
- Support resizing game window on desktop systems.
- Support "borderless full-screen window" mode in addition to the real (exclusive) fullscreen.
- Support for switching vertical sync at runtime with Direct3D/OpenGL renderers.
  Also enable vsync in windowed mode too.
- Unicode (UTF-8) text support: engine can now switch between ASCII and UTF-8 text mode.
  This is controlled by both game's OPT_GAMETEXTENCODING setting and translation's "Encoding" setting: they tells whether to interpret game texts as UTF-8 or ASCII/ANSI.
- Support optional translation's "GameEncoding" setting: it hints the original game's codepage to help with their conversion. This is mostly meant for translating existing older (ANSI) games.
- Engine now supports using real pixel height of the TTF fonts when arranging text and UI elements on screen; using nominal import size of the font is used as a compatible mode for the old games.
- Also supports separate "normal" and backward compatible "fixup" modes when initializing TTF fonts, letting to display both common TTFs and ones made specifically for AGS in the past to display as they were meant to be.
- Supports scripts using functions and variables from any other scripts, regardless of the script module order in the project.
- Removed limit of simultaneous Button animations.
- Removed limit of Character followers.
- Removed Overlay limit.
- Character.SetWalkSpeed() is no longer restricted by an arbitrary limit of 50.
- Process character's idle view based on real game speed, not hardcoded 40 fps.
- Improved file writing times (e.g. when doing a game save) by using buffered file stream. Initial tests showed 50% faster file writing.
- Engine now renders GUI controls as separate textures when using hardware accelerated renderers. This may significantly improve perfomance in the high-resolution games and games with large number of GUI elements on screen.
- Engine now shares the video texture data for all game objects on screen sharing same sprite. This improves performance in case there are multiple objects which use same image.
- Various performance optimizations for both raw drawing and texture updates (Direct3D/OpenGL).
- Engine now ensures that in threaded audio mode the AudioChannel's state only changes once the game is updated, and not while the game script is running. This prevents situations when the clip could begin playing before all properties are set in script, or when AudioChannel's properties' values (such as Position) could change while running a game script.
- 24-bit wav PCM support, comes with the new sound library.
- File.ReadRawLineBack() now always reads full line, and not limited to 200 characters anymore.
- Debug displays, such as showing room mask and character walk paths, are now implemented as non-blocking translucent overlays, allowing you to keep playing the game while they are on.
- Implemented debug key controls for calling a built-in save and restore game dialogs. These controls have to be set in user config as "save_game_key" and "restore_game_key" in "[override]" category. These may be used by testers if the game is missing a save function or one is bugged.
- Engine now supports loading compiled scripts as separate files packed along with the game, along with those embedded into the main game data or inside room files.
- Engine no longer bails out with error if the chosen translation cannot be loaded on startup.
- When reporting script errors, engine will print callstack for all the active script "threads": for example, if there's Wait() function called and error happened in repeatedly_execute_always, then it will print both actual error's location, and Wait() call's location.
- Engine config now has graphic modes defined as a simplier string options:
  "[graphics] fullscreen" for the fullscreen mode setup, and "[graphics] window" for the windowed.
  Fullscreen option can explicitly define a "borderless full-screen window" mode.
- Added "emul_mouse_mode" and "emul_mouse_relative" options to config in "[touch]" category.
- Added "cache_size" and "stream_threshold" options to config in "[sound]" category, they setup the rules for sound caching and choosing whether to load a clip fully into mem or stream one.
- Added "load_latest_save" and "show_fps" options to config in "[misc]" category.
- Added "background" option to config in "[misc]" category, that defines the starting run-in-background (aka multitasking) mode (may later be changed by SetMultitaskingMode()).
  Added "--background" command line option for the same purpose.
- Added "--sdl-log" command line option for setting up SDL2 library output verbosity. The engine log config now has a new "sdl" group meant for SDL2 messages.
- Support "--user-conf-dir" command-line arg (and "user_conf_dir" config option) superceding "--localuserconf"; the new option directly tells the location of user config file.
- Path related command-line and config options, - such as "shared_data_dir", "user_data_dir" and "user_conf_dir", now support $GAMENAME$ token in path which is resolved to the game's title.
- Added "--clear-cache-on-room-change" command-line arg (and similar config option).
- Don't error when DrawingSurface.DrawImage has bad transparency parameter (warning instead).
- Don't error when detecting bad format in File.Read* functions (warning instead).
- Added missing "DrawSprite" function for "agsblend" plugin stubs.
- Added stubs for agsshell plugin (a contemporary cross-platform variant of ags_shell).
- Added stubs for agsappopenurl plugin.
- Fixed loading pre-3.5.0 games on big endian systems.
- Fixed potential crashes if a room-related API function has been called in "game_start"; this is achieved by having a dummy room placeholder object. Still results of such calls are undefined and should not be relied upon.
- Fixed potential crash on room load if the walkable area mask contained color values above the supported range.
- Fixed dialog script's "goto-previous" command not working if used from the first sub-topic run using "goto-dialog" (a very-very old bug).
- Fixed AGS_EngineInitGfx plugin callback was not called during OpenGL renderer initialization.
- Fixed Direct3D/OpenGL renderers were displaying plugin's raw drawings in a wrong position in the scrolling rooms, if the drawing was done on AGSE_PRESCREENDRAW or AGSE_POSTROOMDRAW events.
- Fixed overlay may fail to be created sometimes, if previously another overlay had been forcefully removed when changing rooms (this is an ancient bug which existed for many years).
- Fixed ListBox.RowCount reporting 0 if called before the control was displayed once.
- Fixed GetTextWidth would still return a size of an outline for an empty text string.
- Fixed text may be misaligned in gui controls, as its outline thickness is not counted.
- Fixed some TTF fonts could be cut at the bottom when the speech is displayed.
- Fixed scheduled sound fadeout effect was not cancelled by skipping a cutscene.
- Fixed OGV Theora videos positioned incorrectly if they have certain sizes or aspect ratios.
- Fixed game fps sped up if SetGameSpeed() is called repeatedly in game script.
- Fixed game not reacting to system close commands when stuck in script, which made it impossible to close the "hanging" game by usual means (other than terminating the process).

Engine Plugin API:
- Added IAGSEngine::GetGameInfo() function which returns information about the game, such as its title and GUID.
- Added new render callback AGSE_POSTROOMDRAW, for handling drawing inside the room above all room objects.
- Added IAGSFontRenderer2 interface, expanding the original font renderer interface, improving font plugins support.
- Added ReplaceFontRenderer2() and NotifyFontUpdated() functions.

Compatibility:
- Fallback to the first loop with frames if current character's loop does not have any.
- Use the dummy frame if current character's speech view loop does not have any.
- Ignore character having view/loop with no frames while it's not in the current room.
- Legacy behavior of MoveCharacterBlocking's return value.
- Fixed walkable area's continuous scaling was broken for high-res rooms in old games.
- In pre-3.* games force player to walkable area after changing rooms, this is to emulate an unintentional effect created by the old engines.
- Fixed pre-3.4.1 anti-aliased TTF fonts display (their vertical position was broken).
- For pre-3.5.0 games support old behavior of coincidental dynamic sprite replacement on GUI backgrounds (and few other places) without explicit assignment; that is - when the new DynamicSprite is created right after deleting an old one.
- Support Label.TextAlignment with legacy alignment constants for pre-3.5.0 games made with the custom engine from "Clifftop Games".
- Support native resolution hack for games made with "Clifftop Games" custom engine, where 640x400 games are run as 640x360.

Android:
- Rewrote universal AGS game launcher/player using up-to-date Google guidelines. The former "launcher" is now called "AGS Player".
- Implemented single game project template meant for building your own signed APK.
- Implemented two touch-to-mouse control scheme (selectable in config), for one finger emulating LMB only, and for two fingers emulating LMB and RMB.
- Support relative motion speed setting for touch-to-mouse emulation.
- In AGS Player added "Browse" button to the game folder selection, which opens default system file picker.
- AGS Player now searches for games recursively, in all the subfolders.
- AGS Player now has preference button per each game, which opens individual game's settings.

OSX:
- OpenGL renderer is now supported on MacOS.

Web / Emscripten:
- Initial port release.

Windows:
- Installer will create program links with three-digit version in the name.

Plugins:
- Added SpriteFont plugin to the list of builtins, for ports that use ones. SpriteFont plugin is updated to support custom "Clifftop Games" font variants.

WinSetup:
- Added "Fullscreen as borderless window" checkbox.
- Remade sound options to reflect the move to the new audio system in the engine.



KNOWN ISSUES
* MIDI no longer plays on its own on Windows. For MIDI you (and your players) must install "sound banks" (also known as "sound font"). Please refer to this article: https://github.com/adventuregamestudio/ags-manual/wiki/MIDI-playback
* AudioChannel.Position and AudioChannel.Seek do not work for MIDI and MOD sounds. Try sticking to PositionMs and SeekMs for now.
* There are reports about Direct3D not being able to restore the fullscreen mode after alt+tabbing occasionaly.

[WARNING:]

This is an upgrade of the older "Direct3D" plugin by AJA, which was used to display Theora videos in AGS, and also freely display sprites with various transformations (without creating standard game objects).

WARNING: neither the original plugin nor this reimplementation play any sounds from videos, they only display video frames. Adding sound support might be a goal for the future versions, but it's not in the immediate plans.

The original plugin was a nice addition as it worked around some engine's limitations, such as being unable to display video non-blocking or while keeping some other objects on screen (like GUI or cursor); or randomly creating scaled and rotated sprites on any layer in game. Not much changed since, except maybe in AGS 3.6.0 Overlays now come close to this plugin's sprites abilities.
But the older plugin also had a significant limitation, as it was made for an older engine, it did not support anything besides Direct3D renderer on Windows.

This new upgraded version, called "SpriteVideo", now has following major improvements:
* OpenGL renderer support;
* May be built for Linux;
* Potentially maybe will work on Mac and Android, but not yet configured the project for that.

Another important part is that this plugin is purposely made 100% script compatible with the old plugin, which means that you may simply replace it in your game project and all the scripts will continue to work. In fact, you may even rename new plugin's dll into "ags_d3d.dll", replace it in the game folder, and it should hook up correctly.

Documentation:
https://github.com/ivan-mogilko/ags-spritevideo/wiki

The plugin is currently in the "test stage", and I will be interested to see how it works with existing games that used the original plugin. My primary goal at this point is to make it complete and stable substitute for "Direct3D" plugin.

Downloads:
Updated 24 April 2023
For Windows: https://github.com/ivan-mogilko/ags-spritevideo/releases/download/v0.9.4/win_ags_spritevideo.zip
For Linux (debian-based): https://github.com/ivan-mogilko/ags-spritevideo/releases/download/v0.9.4/libags_spritevideo.tar.xz
Source code: https://github.com/ivan-mogilko/ags-spritevideo

TODO for v1.0:
* Testing in some real games.
* Bug fixing

[technically]

There have been some improvement to Overlays in 3.6.0, and generally improvement to perfomance of GUI and overlays since 3.5.1, I've been also looking for other opportunities to make Overlays more useful in the long run at a low effort cost (since 3.6.0 is in Beta, I would not want to do any serious code rewrite in this version). There are couple of ideas that technically should not be difficult to implement, but would require some good solution script-wise. Even if these won't get into 3.6.0, this still would be interesting to discuss.

These ideas are:
1) Overlays without sprite copy, but with a sprite reference;
2) Room Overlays.



1. Overlays with a sprite reference

Right now Overlays work with a full sprite copy. I guess this may be because they were first created as textual objects, and later expanded to also have sprite on them.
This makes it easier to create textual overlays, as you just have to pass a string into Overlay.CreateTextual. This also makes it somewhat easier to create graphical ones with Dynamic Sprites, as you don't have to keep that sprite anymore: as soon as overlay is created - it has a sprite's copy, and dynamic sprite may be disposed. Unlike that, if you're using dynamic sprites as object graphic or view frame, you must keep that sprite in a global variable at all times, otherwise the object will loose its graphic (in the past it also crashed the game, but not anymore: now it simply resets it to sprite 0, for safety).

Unfortunately, such approach backfires when you are reusing the sprite on several objects, in other words - either a) displaying same sprite often, and especially if b) using multiple overlays to display a larger numbers of identical images. Overlay itself is a simple struct, but each time when created it also copies the sprite. That makes its creation slower, and increases the overall memory use. In fact, it also increases the disk space needed for a save, as all overlays must write their bitmaps into the save file; which is quite silly if you used a regular sprite from the game resources to create them.
This is even more sad as overlays today are the only object in AGS that may be created at runtime in script. On one hand you may use it to generate graphic scenes on the fly, on another - it is not as optimized as it could be.

There's another consideration here. As you might know, AGS uses "sprite cache", that is - it caches often used sprites in memory to keep them ready and not load/allocate over and over again. Unfortunately, it does not do the same to textures when running Direct3D or OpenGL renderers. That is a general issue, and rather annoying one, as it makes these renderers actually somewhat slower* and more memory consuming than they could be (*slower in one thing, but thankfully they still balance this with being faster in others). I think that one of the future improvements (and quite overdue) is to also cache the textures prepared for particular sprites. If that's done, then whenever you assign a sprite repeatedly, not just the sprite won't be reloaded, but also the texture won't be recreated but taken from the cache instead and shared between multiple objects.

But even if that's done, with overlays things would remain the same, so long as it's function is based on a sprite copy.

So, what is that script problem in this situation? Technically there's little issue: just don't make a image copy and add a sprite reference instead.
But if this is done, that would change the known overlay's behavior, where user may paste a dynamic sprite over it, and discard the sprite object. Instead they would have to make global variables for these sprites and keep a record on them, deleting these when no longer necessary, etc.
Perhaps this is also a problem with the dynamic sprite management in AGS, as their references are not contained in some storage where they will be "safe" from occasional loss, but must be referenced by a script variable.

EDIT: Another difference between having a sprite's copy and a reference is that you may continue editing same sprite after assigning it to a game object. If an object has sprite's copy - then it won't receive further changes. If it has a reference - then it will be automatically updated as soon as you finish editing the sprite (call to DrawingSurface.Release()). /EDIT

What could be a solution here script-wise, if we would like to allow Overlays with a sprite reference instead of a copy? Should there be a new function, that explicitly sais that it's not copying the sprite? Or, on contrary, a function that sais that it makes a copy, while CreateGraphical would make a reference? Are there any alternate ideas maybe?

In regards to dynamic sprites, that may be a separate question (or is it?), but one idea is to treat their assignment to an object as a proper counted reference, thus making them not automatically disposed while their number is assigned to at least one game object.



2. Room Overlays

IMHO this is a interesting idea. Overlays are unlimited (since 3.6.0), easy to make in script, but they are always on top of the room. They received ZOrder property in 3.6.0, so now may be freely sorted among GUI.
In my opinion, it's technically not hard to allow have them inside the room, where they sorted among the room elements (objects, characters and walk-behinds). This opens very good opportunities for setting up temporary visual effects inside the room, as well as generate room scenes in script. Especially since other objects are fixed, and cannot be created or deleted at runtime right now (that would require significant change to how AGS is designed, and is a separate big topic).

But the question that I have is again, how to organize this in script to make convenient? Having a boolean argument in CreateGraphical / CreateTextual is simple, but may be annoying. It may be an enum, which means "game layer" or something (like, eRoomLayer, eGUILayer). Alternatively, these might be separate pair of functions, e.g. Overlay.CreateRoomTextual and Overlay.CreateRoomGraphical.

What do you think?

[AGS-3.x.x.x-debug.apk]

The old forum thread may still be found here. Please beware that it was started many years ago and may contain alot of outdated information.

This new thread is dedicated to discussing the Android port of AGS engine. Following is a brief cover of the topic.



AGS engine has an Android port that can run on most contemporary devices. [TODO] check device ranges and minimal requirements.
To run AGS games on Android you need a dedicated Android app (APK) and a game data.
We support two kinds of applications: a universal game launcher (aka "AGS Player") that can run just any random AGS game without any extra manipulations, and a single game app that you have to package along with the game data yourself into a signed APK. The latter may be then distributed by game shops, such as Google Play.

Currently the v3.x.x engine branch supports running games created with AGS 2.50 and higher.



AGS Player

"AGS Player" is a universal game launcher on Android, that displays a list of found AGS games and lets you run them.

This launcher requires games to be unpacked, placed in the internal storage or sd card, one game in its own subdirectory. You may use raw game data (*.ags files), or even games compiled for other platforms such as Windows ( Windows version of a game is usually just an engine exe with game data appended to it).

We distribute AGS Player with every release of AGS. The download link may be found in respective forum posts for each release.
Another place to find them is releases page in our repository: https://github.com/adventuregamestudio/ags/releases
In the Assets look for AGS-3.x.x.x-debug.apk and AGS-3.x.x.x-release.apk (these are same program, built with debug or release configuration).
If you'd like to build it yourself, you may do so following these instructions: https://github.com/adventuregamestudio/ags/blob/master/Android/README.md

After installing one on your Android device, run it and open the [...] menu, choose "Select game folder". Then type the path or browse to the parent folder you keep all your AGS games in (NOTE: browse button is added since v3.6.0).
You will see the list of all games that the AGS Player detected in that directory. Note that since v3.6.0 the search is recursive, displaying games also found in subfolders.
Touch the game name to run one.

KNOWN ISSUES

1. Please be aware that most AGS games are made not having touch screen in mind. We therefore cannot guarantee (or be responsible for) positive gaming experience. The port provides basic touch controls, and these may be configured to some degree, but they may not be convenient at all times. We accept suggestions for improving these controls, so long as these are universally useful (not meant for a specific game). Ideally the game should be adjusted for mobile/touch controls by their authors.

2. If the game requires engine plugins to run, these have to be included into the launcher APK. We include several plugins by default, mostly ones that were popular among AGS game authors in the past. We may probably expand the list of these plugins if there will be a demand for it.



Building games for Android in the Editor

Editor also comes with an optional feature that lets you deploy for Android using a ported engine.
To use this feature make sure you have installed the "Android build component" along with the editor. This creates a "Android" subfolder inside the Editor's program folder. After that a "Android" option will become available for selection in "Build targets" list in the General Settings of your game project.
You would also require Android Studio.

Before running the build you will have to configure paths to Android SDK and other options. This is done in File->Preferences dialog, on "Android" tab. These options will be used for all your games.
The "Android" section in General Settings is used to configure individual game's properties related to Android build, such as game name, and package format.

The compiled game will be placed into Compiled/Android folder.

For detailed information please see this dedicated forum post:
https://www.adventuregamestudio.co.uk/forums/index.php?topic=59772.0



Building single game APK without Editor

If you'd like to have your individual game APK which you may distribute, or even sell on e.g. Google Play, you have to build one by combining following components:
- The Java/Kotlin application. We provide an project template for this: https://github.com/adventuregamestudio/ags/tree/master/Android/mygame
- The native engine module (and optionally plugins) in the form of dynamic libraries (*.so). You may either build these yourself following instructions in the README, or get prebuilt ones attached to corresponding AGS release. The archive is called AGS-3.x.x.x-android-libs.
- Your raw game's data found in Compiled/Data folder after compilation.

For building the full APK you will be also requiring Android Studio and some other tools.
The process is explained in this dedicated readme: https://github.com/adventuregamestudio/ags/tree/master/Android/mygame#readme

If you encountered bugs or have feature suggestions, you may open an issue in our tracker.



Any other useful information may be added to this post later.

[KNOWN ISSUES]

The old forum thread may still be found here. Please beware that it was started many years ago and may contain alot of outdated information.

This new thread is dedicated to discussing the Linux port of AGS engine. Following is a brief cover of the topic.



AGS engine runs on 32-bit and 64-bit Linux.
To run AGS games on Linux you need the Linux engine and a game data.
The same game data may be run by any engine port. Some ports require repacking it up in certain way (e.g. packing into APK for Android). For Linux this is not necessary.
Note that you may even use games created for e.g. Windows, because Windows version of a game is usually just an engine exe with game data appended to it. Normally any engine port can detect the game data in a file and load it up itself.

Currently the v3.x.x engine branch supports running games created with AGS 2.50 and higher.

If you have an engine executable coming with the game itself you may run it, or use a startup script supplied by the game authors.
If you have an engine installed on your system, all you have to do is to go into the game's directory and run the engine from there. Alternatively: run the engine, passing path to the game dir as a command line argument.

More information about command line args and runtime configuration may be found in our repository:
https://github.com/adventuregamestudio/ags/blob/master/OPTIONS.md



Building games for Linux in the Editor

When you compile your game using the Editor, it produces "raw" game data in Compiled/Data directory. These files alone may be enough to run a game using an engine port.

However, Editor also comes with an optional feature that lets you deploy for Linux using a prebuilt Linux engine and libraries. Please note that these will normally run only on Debian and related systems (Debian, Ubuntu, etc). For other systems you, or your users (players) would have to either build an engine from sources or get one from the system's maintainers (see more info below).
To use this feature make sure you have installed the "Linux build component" along with the editor. This creates a "Linux" subfolder inside the Editor's program folder. After that a "Linux" option will become available for selection in "Build targets" list in the General Settings of your game project. The compiled game for linux will be placed into Compiled/Linux folder.

KNOWN ISSUES

1. As of time of writing, because the linux files will be deployed on a Windows machine, the engine and launch scripts will loose their "executable" flags. The only known solution currently is to move these files onto the Linux machine and set this flag there before creating an archive. Alternatively, the users themselves may do that after your game's installation.

2. If your game uses any engine plugins, you MUST supply linux variants of these. If these are not available, the only workaround is to modify the script of your game specifically for Linux version to avoid relying on these plugins or using any plugin's commands. Otherwise the game won't run correctly, or at all.



Getting a stand-alone Linux engine

There are roughly 3 ways you may get a Linux engine onto your system.

1. Our build server makes engine binaries and Debian packages, runnable on Debian and related systems.These may be downloaded from Releases section of our repository:
https://github.com/adventuregamestudio/ags/releases

2. Some system maintainers may include ags engine into the official list of packages; in such case you may install the engine using your system software. Usually that may be found using a package manager on your OS, or asking system maintainers for information.

3. If nothing of above works, or you simply want to, you may build the engine yourself from the sources.
Our repository is: https://github.com/adventuregamestudio/ags
The information on Linux port may be found here: https://github.com/adventuregamestudio/ags/blob/master/debian/README.md

We have a Makefile, so if you prefer using make, then it may be as easy as

Code: ags

cd Engine
make

(assuming you have all the dependencies installed)

If you prefer CMake, then refer to https://github.com/adventuregamestudio/ags/blob/master/CMAKE.md

If you encountered bugs or have feature suggestions, you may open an issue in our tracker.



Any other useful information may be added to this post later.

[UPDATED in 2023]

UPDATED in 2023

Test build: https://cirrus-ci.com/task/5586565305466880
Ticket: https://github.com/adventuregamestudio/ags/pull/1923

UPDATED later in 2023

This is now fully merged into ags4 branch.



It looks like we may be few steps away from actually supporting managed pointers inside managed structs.

To clarify, since not everyone knows why they are not supported, the problem is that engine does not know real contents of the struct at runtime, and does not know which members are pointers.
Because of that it cannot deduce if something inside struct also has to be released. And if there were a managed struct with pointers, these will not get deleted, creating a so called memory leak. Basically, this may lead to program crashing with "out of memory" error, because objects to which these pointers-in-struct point never get deleted.
So we had to artificially forbid them.

The proposed solution was to introduce a so called RTTI - table containing description of all the types in the game script. This table would not only tell which types are there, but also, what members do they have, and which types these members are. Specifically for this problem this description must tell which of these members are pointers.
A related ticket: https://github.com/adventuregamestudio/ags/issues/1259


I did a small experiment for fun, generating such table along with the script data, and letting engine consult it when disposing managed structs.
https://github.com/ivan-mogilko/ags-refactoring/commits/experiment--rtti

And it works - if you create a chain of managed structs in script - it correctly deletes everything when necessary without any memory leaks.

The code above is extremely dirty though, so it will take time to prepare a polished version.

["ags3"]

That became apparent long time ago that developing AGS further becomes difficult while keeping the "luggage" of old functionality, which was mostly kept for running old games and easier project upgrade.
So this is overdue, and we are planning to introduce a "break" in the versions, where the updates are split into two "branches". We currently call these branches "ags3" and "ags4", but these are informal names, and may be given proper names later.

"ags3" is going to be a fully backward compatible version, based on the latest AGS 3.5.0. From now on it will only receive bug fixes, perfomance and utility updates. There will be no new script functions or game features whatsoever.
There's at least one planned update currently, which number will probably be AGS 3.6.0, and its main feature will be change from "Allegro 4" to SDL2 library. AGS used "Allegro 4" for nearly two decades, but it's discontinued, and often not very well suited for the contemporary OSes. As this change comes with new potential problems, there may be lesser updates in the middle (like 3.5.1 etc) when necessary, until SDL2 update works well enough to be officially released.

"ags4" will be a breaking change version, also based on AGS 3.5.0, but having all the deprecated functions cut off. It may also have other things removed, such as certain plugin functions support which are not convenient to keep. This will be the main branch to develop AGS further. It will also be updated to SDL2 library.
It's not known at the moment how it will be developed, there are several priority tasks, but it mostly depends on how much time contributors can spare, so it's too early to talk about any new features.
We do not yet know what number will this version use, but probably we'll skip couple of them to reserve for "ags3" branch, so somewhere in the range of AGS 3.7.0 - 3.9.0.


Related short-term roadmap ticket on github: https://github.com/adventuregamestudio/ags/issues/1121

[Latest source code may be found here]

DOWNLOAD TypedText 0.7.0 (beta version) MODULE PACK
Archive contains modules: TypedText, TypedTextHelper and TypedTextDrawing.
DOWNLOAD Demo Game

Latest source code may be found here
Git cloning address: https://ivan-mogilko@bitbucket.org/ivan-mogilko/ags-script-modules.git
Demo Game git cloning address: https://ivan-mogilko@bitbucket.org/ivan-mogilko/ags-script-demos.git

Module supports AGS 3.2.1 and higher


Introduction

TypedText module provides means for displaying continiously typed text, also known as typewriter style display. Letter appears by letter with certain delay in between.

A while ago I was scripting a typing text animation for a game project; later I found out that there is already Phemar's Typewriter module, but it did not allow the kind of behavior that the project required, so I continued with my own script.
Now I found some free time to rewrite that script in a cleaner way and make an actual script module of it. But I also copied few things from Phemar's module, to make TypedText suitable for the needs of people who used Phemar's module before.

The general peculiarity of this module, and also what makes it different from existing one, is that it is based on a Type (struct), and objects of that type, instead of a Function. This leads to following effects:
1. You can have multiple typed text animations simultaneously.
2. Since objects keep their states in them, you may have both blocking and non-blocking typed texts.
3. Having an object with exposed interface (public functions and properties) make it possible to alter its behavior on fly, as well as override it, and use it to create your own custom typewriters.


Using an object may be more complicated than using a single function, and require time to study it, so I added TypedTextHelper module with number of "helper" functions to make it easier to start using TypedText in your project. Also those functions may be just what you need if standart behavior is enough. This is why I will explain their use before going into detail about TypedText itself.

But first I need to quickly clarify on some concepts.


TypedText concepts

TypedText simulates continious text typing, letter by letter. When doing so it passes several states:

Inactive - this is when it has no text set whatsoever.
Typing text - this is when it is in process of typing text.
Waiting for reader - this is when all text was fully typed and displayed on screen, but settings demand TypedText to wait a little longer to give human an opportunity to finish reading the text.
Idling - this is when typing and waiting is complete, and TypedText is not going to do anything else.

NOTE: Helper functions, such as those that display TypedText on Overlays, rely on "waiting for reader" state to know when typed text should be removed from screen.

TypedText has a concept of the flashing caret. Depending on setup, it may flash last typed letter, or draw certain symbol behind typed text (like '_', for example).
The caret, if enabled, commences to flash whenever delay between two typed letters is greater than caret's waiting timer. This timer resets when next letter is typed. This also means that when all  the text was already typed, caret will then flash endlessly (so long as TypedText is on screen).

Keeping the above in mind, TypedText relies on following parameters:

Typing delay - how many game ticks to wait after each typed letter.
Typing delay style - this concept is copied from Phemar's module, and defines delay behavior for spaces and caret-returns in the text (are they same, slower than usual or faster than usual),
Caret depiction - is the caret is depicted anyway, and how: this may be flashing last letter, or specific string drawn in the end, or even a sprite - for the advanced TypedText implementations.
Caret flash times - how long caret stays on screen and stays hidden when it flashes.
Text reading time - how much time, in game ticks, is spent on reading 1 letter: this parameter is used to calculate average reading time of a text.

Finally, extended variants of TypedText also support sound that is played whenever next letter was typed.


Using TypedTextHelper

TypedTextHelper module requires TypedText module to present above it in the modules list.

It provides a number of functions to run typed text blocking or non-blocking, in a number of ways: on a Button, on a Label, or on an Overlay.

Because TypedText has a significant number of parameters, many of which are supposed to stay same for the most of the time in game, I thought it would be very inconvenient to put all of those parameters into functions. Instead, TypedTextHelper has a special preset system.
This works pretty simple actually: you setup least changing properties as a preset under certain ID, and then use that preset ID when starting typed text on Label, or Overlay; this makes all of that preset's parameters to be used for that instance of text typing.

Following are preset functions you may use:

Code: ags

/// Set general parameters for the specified preset
TypewriterPreset.SetGeneral(int preset, int delay_min, int delay_max, TypedDelayStyle style, int read_time = 12);
/// Set caret parameters for the specified preset
TypewriterPreset.SetCaret(int preset, int flash_on_time, int flash_off_time, TypedCaretStyle style, String caret_str, int caret_sprite = 0);
/// Set sound parameters for the specified preset
TypewriterPreset.SetSounds(int preset, AudioClip *type_sound, AudioClip *caret_sound, AudioClip *end_sound);
TypewriterPreset.SetSoundArray(int preset, AudioClip *type_sounds[], int type_sound_count,
                                 AudioClip *caret_sound, AudioClip *end_sound);

Maximal number of presets is determined with TYPEDTEXTHELPER_MAXPRESETS constant in the module header. It is 8 by default, but you may increase it if you need more.
Maximal number of sounds that you may assign for preset and each typewriter is determined with TYPEDTEXTRENDER_MAXSOUNDS contant.

Best place to set preset's parameters is "game_start" function, but you may change them anytime by using same preset ID.

After you set up at least one preset, you may begin using helper functions. All of them are made as extender functions, which means you first type object (Button, Label, Character) pointer name, then call the function from it, like:

Code: ags

// NOTE: preset is optional, and will be 0 if you don't type anything
/// Print TypedText as a text on button
SomeButton.Typewriter(String text, BlockingStyle bs, int preset = 0);
/// Print TypedText as a text on label
SomeLabel.Typewriter(String text, BlockingStyle bs, int preset = 0);

The only difference is Overlay static extender (static extenders is a new thing since AGS 3.4.0), where you do not use overlay's pointer, but just "Overlay" word:

Code: ags

// NOTE: preset is optional, and will be 0 if you don't type anything
/// Print TypedText as a text on created overlay
Overlay.Typewriter(int x, int y, int color, FontType font, String text, BlockingStyle bs, int preset = 0);

If you are working in pre-3.4.0, you will have to use non-extender function for overlays, called TypewriteOnOverlay, but it works essentially same, and has same parameters (except it is not called from Overlay).


If you run these functions with eBlock, they will display typed text inside of them, and return when typing (and waiting) state has finished.
If you run them with eNoBlock, they will return back immediately, but typed text will work on a background, updated from repeatedly_execute inside the module.

You may run only one blocking typed text at the same time.
Maximal simultaneous non-blocking typed texts is determined by TYPEDTEXTHELPER_MAXTYPEWRITERS constant in the module header. It is 8 by default, but you may increase it if you need more.


Each of those helper functions return unique ID of typewriter. If you want to control that typewriter, such as detect when it stops typing, or be able to cancel it, store this ID in a variable for later. You may then use this ID with TypewriterRunners static functions and properties:

Code: ags

/// Get number of currently running typewriters
int TypewriterRunners.ActiveCount;
/// Get number of maximal supported typewriters that can run simultaneously
int TypewriterRunners.MaxCount;
/// Get whether given typewriter ID is currently running (use unique ID as an array index)
bool TypewriterRunners.IsActive[];
/// Get whether given typewriter ID is blocking (use unique ID as an array index)
bool TypewriterRunners.IsBlocking[];
/// Stop typewriter under given ID
void Cancel(int id);

The principal example:

Code: ags

int tw_id = SomeButton.Typewriter(text, eNoBlock);

<... later ...>

if (TypewriterRunners.IsActive[tw_id])
  TypewriterRunners.Cancel(tw_id); // interrupt typewriter if it was still running

Using TypedText directly

If above helper functions do not do what you like, you may create and use objects of TypedText struct, or any derived structs, directly.

TypedText struct's purpose is to calculate timing and  basic state of the text. It does not draw anything on screen on its own, but calculates and tells how the text should look like at any given moment, letting you to use that information as you see fit. In other words, it tells what is happening, but does not tell you how it should look (and sound) like.


Setting up TypedText is fairly straighforward, here are its configuration properties:

Code: ags

/// Base delay (in ticks) between every typing event
import attribute int              TypeDelay;
/// Bounds for random base delay
import attribute int              TypeDelayMin;
import attribute int              TypeDelayMax;
import attribute TypedDelayStyle  TypeDelayStyle;
/// Time (in ticks) the caret stays shown
import attribute int              CaretFlashOnTime;
/// Time (in ticks) the caret stays hidden
import attribute int              CaretFlashOffTime;
/// Time (in ticks) given to read one text character
import attribute int              TextReadTime;


/// Whitespace/caret-return delay style defines relation of special case
/// delays to the base type delay.
/// Idea is conforming to the Phemar's Typewriter module.
enum TypedDelayStyle
{
  /// wait for the same amount of time as after regular letters
  eTypedDelay_Uniform = 0,
  /// wait twice as long after whitespaces
  eTypedDelay_LongSpace,
  /// wait twice as less after whitespaces
  eTypedDelay_ShortSpace,
  /// randomly choose a style every time
  eTypedDelay_Mixed
};

And its control methods are:

Code: ags

  
/// Gets/sets paused state
import attribute bool             Paused;

/// Clears all text and resets all timers
import void                       Clear();
/// Sets new string, resets all timers and commences typing
import void                       Start(String text);
/// Skips all the remaining typing
import void                       Skip();

/// Update typed text state, advancing it by single tick
import void                       Tick();

Since you are using TypedText yourself, you need to be continiously checking its state in repeating function:

Code: ags

/// Full string that has to be typed
readonly import attribute String  FullString;
/// Part of string that is supposed to be shown at current time
readonly import attribute String  CurrentString;
/// Part of string that was 'typed' during latest update
readonly import attribute String  LastTyped;

/// Tells whether TypedText has active content to process or display
readonly import attribute bool    IsActive;
/// Tells whether TypedText is in process of typing text
/// (return FALSE if either no text is set, or text is already fully typed)
readonly import attribute bool    IsTextBeingTyped;
/// Tells whether TypedText is waiting for the text to be read by player
/// (return FALSE when reading timer has ran out, regardless of other states)
readonly import attribute bool    IsWaitingForReader;
/// Tells whether TypedText is currently idling, either not having a content,
/// or after finishing all the required actions (typing & waiting for reader)
readonly import attribute bool    IsIdle;
/// Tells whether caret should be currently displayed
readonly import attribute bool    IsCaretShown;

/// Gets if the new character was just typed
readonly import attribute bool    EvtCharTyped;
/// Gets if the text has just ended being typed
readonly import attribute bool    EvtFinishedTyping;

One of the simpliest examples for using TypedText is this:

Code: ags

// in GlobalScript.asc
TypedText my_tt;

function game_start()
{
    // Config typed text to your liking
    my_tt.TypeDelay = 4;
    my_tt.CaretFlashOnTime = 4;
    my_tt.CaretFlashOffTime = 4;
}

// Calling TypeSay will start typed text
function TypeSay(string s)
{
    my_tt.Start(s);
}

function repeatedly_execute()
{
    if (my_tt.IsIdle)
    {
        my_tt.Clear(); // clear the text, stop timers ticking, etc
    }
    else if (my_tt.IsActive)
    {
        my_tt.Tick(); // update TT
        String text_to_show = my_tt.CurrentString;
        if (my_tt.IsCaretShown)
            text_to_show = text_to_show.Append("_"); // append caret symbol to the end of the text
        player.Saybackground(text_to_show); // print TT's current text as a player's background speech
    }
}

Using TypewriterRender and its subtypes

There is a number of extended types provided by the module, which add bit more functionality. First is struct TypewriterRender, which extends TypedText, and other structs extend TypewriterRender further.

As was mentioned above, TypedText does not draw anything on its own, only calculates the text's state. TypewriterRender does not do much too, but it adds few more properties and serves rather like a base class for actual visualizing:

Code: ags

/// Caret display style
import attribute TypedCaretStyle CaretStyle;
/// A string (or single character) that represents typewriter caret
import attribute String          CaretString;

/// The only sound to play when a character is typed
import attribute AudioClip *     TypeSound;
/// Array of sounds to choose at random when a character is typed
readonly import attribute AudioClip *TypeSounds[];
/// Number of typing sounds registered
readonly import attribute int    TypeSoundCount;
/// Sound to play when the line break is met
import attribute AudioClip *     CaretSound;
/// Sound to play when the typewriter finished typing text
import attribute AudioClip *     EndSound;

/// Sets the array of sounds to play at random when character is typed
import void                      SetRandomTypeSounds(AudioClip *sounds[], int count);


/// Style of the caret displayed during typing
enum TypedCaretStyle
{
  /// No caret display
  eTypedCaret_None = 0, 
  /// Flash last character
  eTypedCaret_LastChar, 
  /// Draw separate caret at the next assumed character location
  eTypedCaret_Explicit
};

The actual workers are inheriting types: TypewriterButton, TypewriterLabel, TypewriterOverlay. They have respective properties to set up an object they will print text on (or from which perspective), as well as their own overwritten Clear, Start and Tick methods.

Using them you will avoid necessity to draw text yourself:

Code: ags

// in GlobalScript.asc
TypewriterLabel my_tt_label;

function game_start()
{
    my_tt_label.TypeOnLabel = lblTypewriter; // put your actual label's name here
    my_tt_label.TypeDelay = 4;
    my_tt_label.CaretFlashOnTime = 4;
    my_tt_label.CaretFlashOffTime = 4;
    my_tt_label.CaretStyle = eTypedCaret_LastChar; // make last char flash
    my_tt_label.TypeSound = aTypewriterTyping; // set sound to play
}

// Calling TypeOnLabel will start typed text
function TypeOnLabel(string s)
{
    my_tt_label.Start(s);
}

function repeatedly_execute()
{
    if (my_tt_label.IsIdle)
        my_tt_label.Clear(); // remove text when done typing & waiting for the reader
    else if (my_tt_label.IsActive)
        my_tt_label.Tick(); // update text
    // notice that you do not need to point where to print the text anymore,
    // TypewriterLabel already knows that and does printing for you
}

Using TypedTextDrawing

TypedTextDrawing is an advanced struct, extending TypewriterRender, that lets you draw typed text on DrawingSurface. This means you may have typewriter text on literally anything that can give drawing surfaces or have assigned image: room and GUI backgrounds, objects, character frames even (crazy).
Besides, TypedTextDrawing is the only one of the provided types that can draw caret as a sprite.

TypedTextDrawing is located in its own separate module (of same name) and requires TypedText module to work (but not TypedTextHelper).

Setting TypedTextDrawing up is very similar to setting other TypedText subtypes, but you also need to set up its position on DrawingSurface, text color and font, and optionally background color.

What is more important to remember, you must explicitly call Draw function, because you need to pass DrawingSurface pointer to its drawing. It cannot store DrawingSurface once for use later, because that goes against rules of using drawing surfaces (they have to be released right after every use).

Here is some example, that draws typed text on a room's backround

Code: ags

// in GlobalScript.asc
TypedTextDrawing tt_draw;
DynamicSprite *roomBkg; // will keep saved room background

function game_start()
{
    tt_draw.TypeDelay = 4;
    tt_draw.CaretFlashOnTime = 4;
    tt_draw.CaretFlashOffTime = 4;
    tt_draw.CaretStyle = eTypedCaret_Explicit; // draw caret
    tt_draw.CaretSprite = 1010; // put your sprite number here
    tt_draw.TypeSound = aTypewriterTyping; // set sound to play
    
    tt_draw.X = 40;
    tt_draw.Y = 40;
    tt_draw.Width = Room.Width - 80;
    tt_draw.Height = Room.Height - 80;
    tt_draw.Font = eFontText;
    tt_draw.TextAlign = eAlignCentre;
}

function RestoreRoomBkg()
{
    // Restore original room background
    DrawingSurface *ds = Room.GetDrawingSurfaceForBackground();
    ds.DrawImage(0, 0, roomBkg.Graphic);
    ds.Release();
}

// Calling TypeOnDS will start typed text
function TypeOnDS(string s)
{
    if (roomBkg == null)
    {
        roomBkg = DynamicSprite.CreateFromBackground();
    }
    else
    {
        RestoreRoomBkg();
    }
    tt_draw.Start(s);
}

function repeatedly_execute()
{
    if (tt_draw.IsIdle)
    {
        tt_draw.Clear();
        RestoreRoomBkg();
    }
    else if (tt_draw.IsActive)
    {
        tt_draw.Tick(); // update TT
        DrawingSurface *ds = Room.GetDrawingSurfaceForBackground();
        tt_draw.Draw(ds);
        ds.Release();
    }
}

Other script modules by me:
DragDrop module
KeyListener

[MISSING SCRIPT PROPERTIES]

MISSING SCRIPT PROPERTIES - these are properties that set or get something that is already implemented in the engine, but just does not have means to know its value or change it in script.

Please help gather a list of such properties, grouped by object type. In many cases that would be super-simple to add readonly properties (ones that can tell you certain value). Changeable properties are less easy, because they often require to add values to savegame, but they are also should be mentioned.

NOTE: this relates to only things that are already in AGS, not completely new features.
For example:
* you can set a property in the Editor, but cannot read or set it in script;
* there is a script function that changes object's state, but no way to get what current state is.

Such list will be very useful, because engine contributors get reminded about them only once in a while, and these requests got forgotten in the presence of more critical tasks.
I would like to make a table in the first post, which lists the required properties, and status of their implementation.

Property	Type	Comment	Status
Button
Animating	bool, readonly	from Animate()	3.4.1
Frame	int, readonly	from Animate()	3.4.1
Loop	int, readonly	from Animate()	3.4.1
View	int, readonly	from Animate()	3.4.1
Character
FollowedCharacter	Character*readonly	from FollowCharacter()
GUI
BackgroundColor	int		3.5.0
BorderColor	int		3.5.0
Mouse (alternatively make new static CursorModes struct)
Animating[]	bool, readonly
Frame[]	bool, readonly	current animation frame (if any)
ModeAnimated[]	bool, readonly?	array property, get/set whether particular cursor is animated
ModeAnimatedOnlyOnHotspots[]	bool, readonly?
ModeAnimatedOnlyWhenMoving[]	bool, readonly?
ModeView[]	intarray property	get/set VIEW for the mode
ModeHotspotX[]	intarray property	get/set hotspot X for the mode
ModeHotspotY[]	intarray property	get/set hotspot Y for the mode

[AGS 3.2.1 and higher]

DOWNLOAD DragDrop 1.1.0 MODULE
DOWNLOAD DragDropCommon 1.1.0 MODULE
DOWNLOAD Demo game (needs AGS 3.2.1 or higher)

Additionally, latest sources of both the script module and the demo game may be found in this repository:
https://github.com/ivan-mogilko/ags-script-modules

Full documentation for this module is now available here:
https://github.com/ivan-mogilko/ags-script-modules/wiki/Drag-&-Drop-module

Module supports AGS 3.2.1 and higher.


DragDrop and DragDropCommon are two modules that make it possible to drag things around in AGS. What is the difference between these two?

DragDrop module implements an abstract drag-and-drop functionality. This means that the module does not drag any actual game object on its own, but rather calculates the dragging and dropping action, and tells you what and how happens, so that you could script the actual object movement. You might say, this module provides an idea of dragging, rather than dragging itself .

The upside of such approach is that you may script dragging of anything, both standard AGS objects and your own custom things, even non-ordinary pseudo-objects. For example, you may use this module to script dragging a line from point A to B, or draw a rectangle by dragging one of it's corners. The downside is that you have to be ready to do some extra work, and understand scripting well.

When you need to just make normal ordinary game objects dragged around in your game, this is what DragDropCommon module is for. DragDropCommon supports drag-and-drop for Characters, Room Objects, GUIs and GUI controls, and inventory items, right out of the box, only with a minimal setup.

NOTE: DragDropCommon module actually depends on DragDrop module, so you will have to add both to your game if you want to use DragDropCommon.

[UPDATED July 2020]

UPDATED July 2020

The automated builds may be found here:
https://cirrus-ci.com/github/adventuregamestudio/ags

For latest dev version updates (the "master" branch), in particular:
https://cirrus-ci.com/github/adventuregamestudio/ags/master

[Welcome to the AGS Releases forum!]

Welcome to the AGS Releases forum!

This forum is for announcing the releases of the new versions of AGS.

Currently only moderators can create topics here, but regular users may still post in these topics.

There are few notes on posting here.

DO POST here if:
- you want to clarify something about changes in the new AGS version,
- you are getting troubles when installing or running new AGS version, or
- you are getting troubles when running the game produced with new AGS version.

Spoiler

- you want to express how you feel about new version of AGS.

[close]

NOTE: we also have an Issue Tracker for reporting bugs and suggesting new features; the only caveat is that you need a github account:
Official release issue tracker


DO NOT POST here if:
- you need help creating your game with AGS, scripting or using editor in general; these kind of questions should be posted in Beginners' Technical Questions or Advanced Technical Forum,
- you have suggestion on changing something in AGS (add new feature, improve or change how AGS works), or discuss current development; for this please post in Engine Development or Editor Development forums.
- you have questions on using game template, script module or plugin that was released by someone else; in such case please post in template/module/plugin - related thread. Usually such thread may be found in the Modules & Plugins forum.
- you found bugs in a game made by someone else; in such case you should rather post in the game-related thread (look in Completed Game Announcements) or contact the authors of the game elsewise.


These rules may be updated in future if such need arises.

[LIST UPDATED 30 June 2023:]

Pardon me if I missed anything, but has anyone considered to add a sticky topic with a list of open-source game projects for peoples reference?
Just a suggestion, but it may be sticked somewhere in "Completed games" or "Advanced Tech forums" (along with modules, templates and plugins).

There's a wiki page, but it's rarely updated, also not sure if people will guess to look in there first:
http://www.adventuregamestudio.co.uk/wiki/Open_Source_Games

LIST UPDATED 30 June 2023:

* "A Suspicious Date": https://github.com/alkhimey/MAGS-May-19
* "AGS Awards client" (networking code!): https://bitbucket.org/agsa/ags-awards-source/src/master/
* "Aeronuts" (adventure + top-down fighter mini-game): http://shatten.sonores.de/wp-content/uploads/2014/09/AeroNuts_OSS.7z
* "Art of Dying", arcade, distributed with the source: http://www.adventuregamestudio.co.uk/forums/index.php?topic=49687.0
* "Byte of the Draculator II": http://www.vanwijst.com/games/swarm/draculator_source.zip
* "Black Cauldron Remake" distributed with the source (last time I checked): http://www.classic-retro-games.com/Black-Cauldron_118.html
* "Cargo": https://github.com/SpookyFM/Cargo
* "Cart Life", a sim / management game: https://github.com/gondur/cartlife_src
* "Cameras Tech Demo" (technical demo): https://github.com/ivan-mogilko/ags-camdemo
* "Cat Ventures" (uses python scripts for generating Rooms): https://github.com/juanmcasillas/CatVentures
* "Demo Quest", an ancient demo game, uses deprecated script: https://github.com/adventuregamestudio/ags-demo-quest
* "Dungeon Hands" (card game): https://github.com/ericoporto/DungeonHands
* "Eternally Us" distributed with the source: http://www.adventuregamestudio.co.uk/site/games/game/1303/
* "Hell Puppy" (arcade): https://github.com/VacaRoxa/dogfromhell
* "ICBM", a sim-game, distributed with the source:  https://gamejolt.com/games/icbm/57197
* "Last & Furious" (top-down racing): https://github.com/ivan-mogilko/ags-lastfurious
* "Oceanspirit Dennis", a big collection of joke games by various authors: https://www.adventuregamestudio.co.uk/forums/adventure-related-talk-chat/the-oceanspirit-omnibus/
* "Open Quest" (a simple demo game made in 2007): https://www.dropbox.com/s/3g01fjudw71xuld/OpenQuest_AGS.zip?dl=0
* "Read A Book": https://github.com/karjonas/Read-A-Book
* "Rescue Mission": https://github.com/ConeRX/RescueMission
* "Space Pool Alpha": http://www.kweepa.org/step/ags/games/SpacePool.zip
* "The 4th Wall": https://github.com/hewills/the4thwall
* "Three Little Pigs Remediation": https://github.com/KostisMon/Three-Little-Pigies--Remediation
* "Wilfred 2088": https://github.com/hewills/Wilfred-2088


Also for the record:

Spoiler

Here are some previous threads on this topic where people were trying to get a list of open sourced games:
http://www.adventuregamestudio.co.uk/forums/index.php?topic=26688
http://www.adventuregamestudio.co.uk/forums/index.php?topic=32424
http://www.adventuregamestudio.co.uk/forums/index.php?topic=39795

[close]

As many of you should know, we have a number of AGS ports now that let run AGS games on other platforms (linux, etc). Plugins remain a problem, because they were written as Windows dynamic libraries. JJS already rewrote couple of plugins, and Calin disclosed his AGSBlend and SpriteFont plugins, so that their code could be used to compile plugins for other systems too.

Are there anyone else who would like to disclose his/her plugin source to let the games, which used them, become fully portable? Perhaps someone may contact plugin authors that did not visit forums for a while?
Could there be a reason to not to disclose plugin source?

Additionally, I want to mention, that maybe it could be a good idea to state a rule, that AGS plugin should be made open source from the start (NOTE: "open-source" does not mean "free to use")? Aside from portability, this would also ensure that no one will put something unexpected, like malicious code in there.