AGS 3.6.2 - Beta 4 -- a WIP 3.6 update

[Crimson Wizard]

AGS 3.6.2 - Beta 4

Full release number: 3.6.2.4

ACHTUNG!

This is a BETA version of AGS 3.6.2. It's considered relatively stable but is not thoroughly tested yet and also may have planned additions. Use at your own risk. Please back up any games before opening them in this version of AGS. New settings in this version may make your project files unusable in previous versions after saving with this version.

Download AGS 3.6.2 Beta installer

Download AGS 3.6.2 Beta 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: 15th December 2024

Previous stable version: AGS 3.6.1 P8 forum thread


This release is brought to you by:

- Alan v.Drake (palette fix)
- Crimson Wizard
- edmundito (some fixes)
- eri0o
- rofl0r (couple of compatibility reports & fixes)


What is new in 3.6.2

3.6.2 is planned to be a second minor update to 3.6, focusing mostly on convenience of existing Editor and Engine features, and expanding existing script commands. There's however one bigger change: a support for loading saves from older versions of the game.

Common features:
 - Event handler function are now allowed to be located in any script module.
 - New naming rule for the voice clips: full char name, followed by a number, separated by a dot, e.g. "RogerTheGreat.1234.ogg". The old rule may be enabled again by a switch in "Backwards Compatibility" settings.

Editor:
 - In "Start New Game Wizard" game template selection now displays template's description right in the dialog.
 - "Game statistics" now have Ctrl + F2 shortcut instead of F2.
 - F2 can be used for starting editing names of items in the Project Tree (ones that support that) and folders in the Sprite Manager.
 - In General Settings added "Use old-style voice clip naming rule" which lets to select whether the game should expect old-style voice clip filenames (4-letter char name followed by number) or the new one (full char name, followed by a number, separated by a dot).
 - Property Grid now displays Custom Properties right in the main properties list for each item that supports them.
 - Added "WrapText", "TextPaddingHorizontal", "TextPaddingVertical" properties to GUI Button.
 - GUI Labels can select full range of Alignment values in their TextAlignment property.
 - Added "TurnWhenFacing" property to Characters.
 - Textual GUI controls can now select "Null Font" as their font: this will prevent any text to be drawn even if one is assigned, and make it have zero size (when it matters).
 - "Events" tab on the Properties Grid now has "ScriptModule" selection, which lets define in which module should the related script functions be generated and looked for. The GUI Controls use a ScriptModule set in their parent GUI, and Room events always has a fixed room script selected.
 - Added "Open Recent" submenu in the File menu.
 - Sync script editor's commands in Edit menu with the context menu.
 - Added "Toggle Line Comment" command to Edit menu for scripts.
 - More panes in the Editor are DPI-aware (rescale well with the system font scaling).
 - Editor tabs now display icons indicating their contents (may be disabled in Editor Preferences).
 - Room panel tabs now display room names.
 - Editor will now remember certain window states: "Sprite selector" window and splitter position, splitter position in "Sprite manager".
 - Support reordering folders in Project Explorer with drag & drop.
 - Support importing plain script files: ash, asc or both, - besides script modules (*.scm).
 - On "Color Finder" pane also display actual RGB values that the engine will use. They may be different from requested RGB, because historically engine limits drawing color's RGB precision to 16-bit.
 - Font's "SourceFilename" and "Font Size" properties now have buttons that let import another font file, or reimport same font with different size respectively, instead of clicking on a button on the preview window.
 - Global Variables panel now allows to declare arrays.
 - Added "Controls transparency" slider to GUI edit pane.
 - Copy, paste and delete commands now apply to all the selected GUI controls in GUI editor.
 - When pasting a copied GUI control, Locked property of a new control will be turned off.
 - Support editing group properties for selected GUI controls.
 - Added a multiline Text edit window for Button and Label controls, that may be called by Ctrl+E, from context menu, or by pressing "..." button of the Text property in the Properties grid.
 - Support reordering folders in Sprite Manager with drag & drop.
 - Support importing 1-bit (monochrome) and 4-bit images as sprites, room backgrounds and masks (converted to 8-bit).
 - Support importing indexed PNGs as room backgrounds and masks.
 - Do not alter or clamp palette for 8-bit sprites imported in a 16/32-bit game.
 - Removed obsolete "Copy walkable area mask to regions" command from the Room editor.
 - Improved scrolling of drop-down lists in the Room's navigation bar: made scroll buttons larger, and support mouse wheel.
 - In Room Editor, during any area drawing mode Ctrl + LMB now works as area picker regardless of the currently selected tool.
 - Do not delete previously built game exe from Compiled/Windows folder when testing a game from the editor.
 - Editor will now report any missing script functions that are assigned to events, but not present in script, as warnings when compiling the game.
 - Editor will now report any script functions that *look like* event functions, but not assigned to corresponding events, as warnings when compiling the game.
 - Added "/maketemplate" command-line option that tells Editor to run, make template out of the said game, and quit.
 - Fixed Editor refusing to open a project if one or more of the sections are missing in the file.
 - Fixed dragging an item into the folder in Project Explorer could move it into a wrong folder if the folders have similar names only different in letter case.
 - Fixed importing indexed PNG as a sprite, previously Editor would mistakenly treat the source image as 32-bit.
 - Fixed importing 8-bit BMP sprites with no "Remap palette" and "Leave As Is" as a transparency option would still remap palette index 0 to the first found palette entry with Alpha 0, even if that's a filler entry not used by the image.
 - Fixed exporting room backgrounds was always writing a 32-bit image rather than using actual background's color depth.
 - Fixed "Color Finder" and color properties were mapping a color number to RGB values with accuracy mistakes, resulting in slightly different values than the engine would use.
 - Fixed an unhandled exception occuring when rebuilding rooms if any script's header is missing.
 - Fixed double warning message when trying to close the Editor while a game test is running.

Scripting:
 - Dynamic arrays now have Length readonly property that returns their number of elements.
 - Support zero-length dynamic arrays. This may be useful if you need to have a dynamic array with no elements, but don't want to bother about checking a null pointer.

Script API:
 - Added eNullFont constant that lets assign or pass a "null font" to any property or function parameter which expects a font's ID. This "null font" will simply make any text not drawn and have no actual measurements (size, spacing, etc).
 - Added global events: eEventDialogStart, eEventDialogStop, eEventDialogRun, eEventDialogOptionsOpen, eEventDialogOptionsClose (these are handled in "on_event").
 - Events eEventGUIMouseDown and eEventGUIMouseUp now get additional parameters: mouse button, mouse x and y positions.
 - Expanded "on_mouse_click" callback, now supports two more parameters: click x,y coordinates.
 - Added RestoredSaveInfo struct which contains information about game save's contents,
 - Support "validate_restored_save" callback, which lets user to validate restored saves with mismatching data and request cancellation or continuation of restoring this save.
 - Added Button.WrapText, TextPaddingHorizontal, TextPaddingVertical.
 - Added Character.Following property that returns another Character that this one follows after.
 - Added Character.TurnWhenFacing property.
 - Added Character.MoveStraight() complementing WalkStraight().
 - Added DateTime.CreateFromDate() and CreateFromRawTime().
 - Added static Dialog.CurrentDialog property and non-static ExecutedOption and AreOptionsDisplayed properties.
 - Added RenderLayer enum, and optional "layers" parameter to DynamicSprite.CreateFromScreenShot(), that tells which of the game's render layers to capture when making a screenshot.
 - Added File.Copy() and File.Rename().
 - Added FileSortStyle and SortDirection enum, and File.GetFiles() function that returns a dynamic array of filenames found using certain pattern, and optionally sorted by name or time, in ascending or descending order.
 - Added File.GetFileTime() that returns file's modification time.
 - Added File.ReadBytes(), File.WriteBytes(), File.ReadRawFloat(), File.WriteRawFloat().
 - Added SaveGameSortStyle enum and Game.GetSaveSlots() function that returns a dynamic array of save slot indexes, optionally sorted in certain way.
 - Added Game.GetSaveSlotTime() that returns a time this save slot was last written.
 - Added Game.ScanSaveSlots() that scans a range of game saves and tests them for compatibility, using "validate_restored_save" too if it's present in user script. This action is not run immediately, but is scheduled to be executed after current script ends. It reports of scanning completion by sending eEventSavesScanComplete event.
 - Label.TextAlignment has now type Alignment, rather than HorizontalAlignment, and has full alignment range (both horizontal and vertical).
 - Added optional "fileSortStyle" and "sortDirection" parameters to ListBox.FillDirList().
 - Added optional save slot range (min/max), saveSortStyle and sortDirection parameters to ListBox.FillSaveGameList(). This lets to define the exact range of saves it should fill, and order them in desired way.
 - Added ListBox.FillSaveGameSlots(), which initializes a list of saves from a dynamic array of save slot indexes.
 - Added Object.DestinationX and DestinationY properties, complementing ones in Character.
 - Added Overlay.SetPosition() and SetSize() functions for convenience.
 - Added Speech.SpeakingCharacter that returns currently speaking character (for blocking speech).
 - Added GetTimerPos() that returns timer's position (remaining time), in ticks.
 - Added CopySaveSlot() and MoveSaveSlot(), which moves existing save to another slot.
 - Added optional save slot range (min/max) parameters to RestoreGameDialog() and SaveGameDialog().
 - Added optional "sprite" parameter to SaveGameSlot(), that lets to pass a number of an arbitrary sprite to write into this save instead of a standard "screenshot".
 - Added SendEvent() function that allows to trigger "on_event" function calls in script. Special event value eEventUserEvent may be used as a base index for user-defined events.
 - Added System.DisplayFPS property that toggles FPS counter (a replacement to Debug(4, 1)).
 - Added System.GetEngineInteger() and System.GetEngineString() for returning diagnostic information about engine's runtime state. Possible arguments are defined by EngineValueID enum.
 - Added new game-wide option OPT_SAVEGAMESCREENSHOTLAYER that lets to define which of the game's render layers will be captured when making a standard screenshot for the save game.
 - Add SaveComponentSelection enum and game option OPT_SAVECOMPONENTSIGNORE, which lets to skip certain components when saving or restoring a game. This has dual purpose: reduce number of things in game that may break older saves by simply not having them in a save, and also reducing the size of game saves on disk (e.g. in case of dynamic sprites). Note that all things that were not restored from the save will retain their *current state*.

Engine:
 - Engine now potentially supports reading saves made in older game versions with different content, so long as these saves have *less* data in any given type (i.e. less Characters, or less controls on a certain GUI, or less variables in script, and so forth).
   This feature is enabled by having a special "validate_restored_save" function anywhere in the game script, that accepts an argument of type RestoredSaveInfo. RestoredSaveInfo contains various information about the restored save, and "Cancel" property, that must be explicitly set to "false" in script in order to allow to restore such save.
 - Engine supports returning to previously saved rooms which have less script data.
   It's important to remember though that it does no validation of restored room state on its own.
 - Dropped support for pre-3.5.0 game saves.
 - Engine no longer quits with error in case a script function assigned to a Room event is missing. Logs warnings about missing script functions assigned to any events.
 - Ensure that Character.Speaking returns true when a speech is playing even if the character has no speech view.
 - DynamicSprite.CreateFromFile() may now load 1-bit and 4-bit bitmaps, converting to 8-bit.
 - Do not alter or clamp palette for 8-bit sprites loaded into a 16/32-bit game at runtime.
 - Assigning InventoryItem.Graphic will no longer reassign CursorGraphic too even if they were identical previously.
 - Calling DeleteSaveSlot() on a slot within 0-50 range will no longer secretly move a save with the topmost number (within the same range) to fill the emptied slot. If you still like to recreate this behavior, then use MoveSaveSlot() command.
 - Support calling StopDialog() inside a dialog script, that will schedule dialog's stop command at the end of the current option script.
 - Removed arbitrary limit of 2k bytes for the result of String.Format().
 - Implemented video buffering on a separate thread. Allow to drop late video frames.
 - Added new accessibility config settings in "access" section: "speechskip", "textskip", "textreadspeed". These let player to override game's skipping style for character speech and text messages, and text reading speed parameter that controls speech timing.
 - Added "max_save" config option in "override" section: this lets to enforce an arbitrary number of saves displayed in a standard save/restore dialogs in game.
 - Added "--no-plugins" command-line argument that denies loading any plugins; also added respective config option "noplugins" in "override" section.
 - Fixed calling Dialog.Start() inside a dialog script would create a nested "dialog state", which could eventually lead to internal mistakes and program stack overflow. Dialog.Start() will now schedule a proper dialog topic switch, equivalent to "goto-dialog" command.
 - Fixed calling Character.Animate() during idling state could cause incorrect error, reporting invalid animation loop.
 - Fixed displaying room masks with Debug command in legacy "upscale" mode.

Engine Plugin API:
 - Added IAGSEngine.Log(), which lets plugins to print using engine's log system.

Compatibility:
 - Fixed loading of games made in AGS 2.55-56 which include plugins.
 - Fixed loading of rare games made with AGS 2.5 or higher, which contained deprecated "room animations" (animations themselves are currently not functional).
 - Fixed old pathfinder imprecision affecting few pre-3.0 games.
 - Allow pre-2.7 games to have RestartGame() command be followed and overridden by a NewRoom(). This is necessary for some older games to be able to proceed.

WinSetup:
 - Redesigned winsetup into a tabbed dialog.
 - Added "Reset To Defaults" button that resets all options to values from the game's default config file.
 - Added "Accessibility" settings for skipping speech and text messages, for text reading speed.
 - In "disabled" section of config "access_skipstyle" setting lets disable all options in setup related to the speech and text skipping.

[Crimson Wizard]

Since documentation for this version is not ready yet, following are declarations of new enums, to make it easier to learn them:

Code: ags

enum RenderLayer
{
  eRenderLayerNone      = 0x00000000,
  eRenderLayerEngine    = 0x00000001,
  eRenderLayerCursor    = 0x00000002,
  eRenderLayerUI        = 0x00000004,
  eRenderLayerRoom      = 0x00000008,
  eRenderLayerAll       = 0xFFFFFFFF
};

enum FileSortStyle
{
  eFileSort_None = 0,
  eFileSort_Name = 1,
  eFileSort_Time = 2
};

enum SortDirection
{
  eSortNoDirection = 0,
  eSortAscending   = 1,
  eSortDescending  = 2
};

Examples:

Code: ags

DynamicSprite* screenshot = DynamicSprite.CreateFromScreenShot(Screen.Width, Screen.Height, eRenderLayerRoom);

Will make a screenshot that only has room viewport(s) on it, but no GUI or else.


EngineValueID are identifiers of value returned by two functions:

Code: ags

int System.GetEngineInteger(EngineValueID value, optional int index = 0);
String System.GetEngineString(EngineValueID value, optional int index = 0);

These are meant primarily for testing and diagnostic purposes, for example, if you like to display current engine state on screen during game tests.

The enum itself is declared as:

Code: ags

// Engine value constant name pattern:
// ENGINE_VALUE_<I,II,S,SI>_NAME, where
//   I - integer, II - indexed integer, S - string, SI - indexed string.
enum EngineValueID
{
  ENGINE_VALUE_UNDEFINED = 0,            // formality...
  ENGINE_VALUE_SI_VALUENAME,             // get engine value's own name, by its index
  ENGINE_VALUE_S_ENGINE_NAME,
  ENGINE_VALUE_S_ENGINE_VERSION,         // N.N.N.N (with an optional custom tag)
  ENGINE_VALUE_S_ENGINE_VERSION_FULL,    // full, with bitness, endianess and any tag list
  ENGINE_VALUE_S_DISPLAY_MODE_STR,
  ENGINE_VALUE_S_GFXRENDERER,
  ENGINE_VALUE_S_GFXFILTER,
  ENGINE_VALUE_I_SPRCACHE_MAXNORMAL,   // sprite cache capacity limit (in KB)
  ENGINE_VALUE_I_SPRCACHE_NORMAL,  // sprite cache capacity filled (in KB)
  ENGINE_VALUE_I_SPRCACHE_LOCKED,  // amount of locked sprites (in KB)
  ENGINE_VALUE_I_SPRCACHE_EXTERNAL, // amount of external sprites, that means dynamic sprites (in KB)
  ENGINE_VALUE_I_TEXCACHE_MAXNORMAL,   // texture cache capacity limit (in KB)
  ENGINE_VALUE_I_TEXCACHE_NORMAL,  // texture cache capacity filled (in KB)
  ENGINE_VALUE_I_FPS_MAX,    // max fps, this is set by SetGameSpeed
  ENGINE_VALUE_I_FPS,      // real average fps (updates along with the game run)
  ENGINE_VALUE_LAST                      // in case user wants to iterate them
};

Example of use:

Code: ags

int spritecachemax = System.GetEngineInteger(ENGINE_VALUE_I_SPRCACHE_MAXNORMAL);
int spritecachecurrent = System.GetEngineInteger(ENGINE_VALUE_I_SPRCACHE_NORMAL);
int spritecachepercent = spritecachecurrent * 100 / spritecachemax;
lblInfo.Text = String.Format("Sprite cache: %d / %d (%d%%)", spritecachecurrent, spritecachemax, spritecachepercent);

[Crimson Wizard]

Updated to Beta 2
(Please use download links in the first post)

Among other things, this update includes few simpler script API additions backported from AGS 4 Alpha release.

Editor:
 - Added "WrapText", "TextPaddingHorizontal", "TextPaddingVertical" properties to GUI Button.
 - GUI Labels can select full range of Alignment values in their TextAlignment property.

Script API:
 - Added global events: eEventDialogStart, eEventDialogStop, eEventDialogRun, eEventDialogOptionsOpen, eEventDialogOptionsClose (these are handled in "on_event").
 - Added Button.WrapText, TextPaddingHorizontal, TextPaddingVertical.
 - Added DateTime.CreateFromDate() and CreateFromRawTime().
 - Added static Dialog.CurrentDialog property and non-static ExecutedOption and AreOptionsDisplayed properties.
 - Added File.Copy() and File.Rename().
 - Label.TextAlignment has now type Alignment, rather than HorizontalAlignment, and has full alignment range (both horizontal and vertical).
 - Added Overlay.SetPosition() and SetSize() functions for convenience.
 - Added GetTimerPos() that returns timer's position (remaining time), in ticks.
 - Added CopySaveSlot() to complement MoveSaveSlot() and File.Copy() functions.


I suppose that this version may not have any more big additions, with an exception of savegame upgrade feature, which I've been preparing for some time:
https://www.adventuregamestudio.co.uk/forums/engine-development/load-older-game-saves-into-updated-game-attempt-2/

I'd like people to try this version out and test how it works.


Once again, since we don't have an updated manual yet, here's some info about the new Dialog-related events.
These let to do certain actions in your game whenever a Dialog starts, stops, or a topic is run. Which may be useful for adding some custom effects to your game.

All of these events are handled in "on_event" function:
eEventDialogStart - arg1 means dialog ID
eEventDialogStop - arg1 means dialog ID
eEventDialogRun - triggers whenever a dialog entry is run, arg1 is dialog ID, arg2 is entry ID, where starting entry (@S) is 0, and user-made options begin with 1
eEventDialogOptionsOpen - triggers whenever dialog options are shown
eEventDialogOptionsClose - triggers whenever dialog options are hidden

Here's a demo game that illustrates their principal usage:
https://www.dropbox.com/scl/fi/vkezgxxrujldunxn4n55o/362-demo-dialogevents.zip?rlkey=yueyy9uymp0d8c0ypntdnpqh1&st=cdrprje1&dl=0
(use TalkTo verb on a player character to start a dialog)

[RootBound]

This all sounds good. I'll try this version with my current game and see what happens.

[Laura Hunt]

- Expanded `on_mouse_click` callback, now supports two more parameters: click x,y coordinates.

This is amazing, I've been wanting this functionality for so long. No more hacking it with GetAtScreenXY!

WinSetup:
 - Redesigned winsetup into a tabbed dialog.
 - Added "Accessibility" settings for skipping speech and text messages.

Will it be possible to disable these options with the [disable] tag in the cfg file, as we can already do for other options like gfxdrivers, filters, etc?

[Crimson Wizard]

WinSetup:
 - Added "Accessibility" settings for skipping speech and text messages.

Will it be possible to disable these options with the [disable] tag in the cfg file, as we can already do for other options like gfxdrivers, filters, etc?

Won't this defeat the purpose of these options? The whole point is to let players override the game in case developer made it impossible for them to play the game. If a game developer will disable them, then players who might need them won't be able to use them.

[Laura Hunt]

Won't this defeat the purpose of these options? The whole point is to let players override the game in case developer made it impossible for them to play the game. If a game developer will disable them, then players who might need them won't be able to use them.

Ultimately I think the final control over what can or can't be done with the game should belong to the developer, and while accessibility features are something that the engine should definitely offer, in the end it should be the decision of the developer whether to actually implement them or not, or which ones to implement. If my game is designed in a way that I feel that overriding my design decisions will cause issues or change the experience somehow, I would prefer to prevent users from tampering with those options.

[Crimson Wizard]

Very well, I will just remove them from the engine and setup, and then provide an alternate program that gives them for those players that need this.

Or perhaps I should suggest ScummVM team to implement these instead, and redirect players to use ScummVM to run ags games when they have these troubles.

[Snarky]

Wouldn't it be better to not make these decisions on a whim or based on one person's feedback?

[Crimson Wizard]

I can add options to disable these.
Because Accessibility group may contain a wide range of settings, then they probably will require separate disable settings per subgroup (or even per individual options in certain cases).

Of course this will open an opportunity for game developers to prevent players from having these options when they might actually need them.

[Laura Hunt]

I can add options to disable these.
Because Accessibility group may contain a wide range of settings, then they probably will require separate disable settings per subgroup (or even per individual options in certain cases).

Of course this will open an opportunity for game developers to prevent players from having these options when they might actually need them.

Appreciate it, CW. I definitely see no need to remove them completely, just giving us the option to disable them like you just said is perfect.

[Dave Gilbert]

These are all amazing new features! Since I'm nearing the end of my current project I probably won't upgrade to this, but next time for sure.

[Crimson Wizard]

These are all amazing new features! Since I'm nearing the end of my current project I probably won't upgrade to this, but next time for sure.

I actually recommend trying out AGS 4 for the new projects instead:
https://www.adventuregamestudio.co.uk/forums/ags-engine-editor-releases/ags-4-0-early-alpha-for-public-test/

It has much more new things, improvements to scripting language, few big features that you've been asking for in the past, such as rooms saved as multiple files (images and data separate) and inspecting script variables during game test.

And frankly we need more people checking it out, to speed up polishing process.

[Dave Gilbert]

Will the 3.6.2 features be rolled into 3.4?

[Crimson Wizard]

Will the 3.6.2 features be rolled into 3.4?

Naturally, AGS 4 will contain everything from previous versions, except old deprecated features.

[Dave Gilbert]

Then I most definitely will! Assuming I survive finishing this project first. 

[RootBound]

Hey @Crimson Wizard

I'm trying out this version for my MAGS entry this month, and I think there's a bug in the editor - when I import over one of the default fonts, the new (imported) font does not display in the editor, and the default font remains. However, when I run the game, the new (imported) font displays correctly, so it has been imported.

On the plus side, the new GUI transparency slider in the GUI editor is nice and seems to work perfectly. I'm also trying out declaring arrays in global variables, so I'll keep you updated on anything else I find as I keep using this version. 

[Crimson Wizard]

I'm trying out this version for my MAGS entry this month, and I think there's a bug in the editor - when I import over one of the default fonts, the new (imported) font does not display in the editor, and the default font remains. However, when I run the game, the new (imported) font displays correctly, so it has been imported.

Please clarify, what do you mean by "import over default font", which operations do you do?

I think editor may fail to refresh the font in memory on some occasions.

[RootBound]

I'm trying out this version for my MAGS entry this month, and I think there's a bug in the editor - when I import over one of the default fonts, the new (imported) font does not display in the editor, and the default font remains. However, when I run the game, the new (imported) font displays correctly, so it has been imported.

Please clarify, what do you mean by "import over default font", which operations do you do?

I think editor may fail to refresh the font in memory on some occasions.

I click one of the default fonts from the blank template and select "import over this font" and then select a new font and import it.

It does seem that closing the AGS editor and reopening it updates the font in the display area.

[Crimson Wizard]

I click one of the default fonts from the blank template and select "import over this font" and then select a new font and import it.

I had a moment of confusion. I've been thinking of a new fonts system in AGS 4, where "import over font" command no longer exists.

Okay, I will test this in 3.6.2.