TOOL: AGS Toolbox🧰 0.5.5

[eri0o]

AGS Toolbox🧰 version 0.5.5

Get Latest Release agstoolbox.exe | companion atbx.exe | GitHub Repo



🚨NOTE: A clean windows 11 installation may require you install this VC_redist.x64.exe (VS2017 redistributable).

Hi, I made something intended for those that deal with multiple versions of AGS Editors and multiple AGS Game Projects. Place the agstoolbox.exe in a folder under your user, like "C:\Users\MY_USER\software", before you run it.



After you run the agstoolbox.exe, you will find a bluecup in your indicator area of your taskbar, near the clock area. Double click or right click it, to open the main panel.

Features

• Editors that you install using AGS Toolbox are called Managed Editors, as they are managed through the tool. Just double click in any Editor available to Download to get one.
• Editors you have acquired through other means (like installed through Chocolatey), are called Externally Installed Editors, directories to look for can be configured in the Settings.
• Game Projects are looked for in directories set in the Settings. It will understand the Editor Version it was used to create, open in it by simply double clicking. You can also use right click to open in a different version.
• You can add it to your Windows initialization if you want a quick shortcut to AGS game development (it's in the settings menu)

Right clicking any item on the list will show available actions, double clicking will execute the command marked in bold.

I made it initially for myself to help handle my own games and modules. It has also an additional pair tool, atbx, that provides the same functionalities through a command line interface - intended for CI and automation.

For people in Unity, this may be a similar AGS version of the Unity Hub. I actually modeled it on the JetBrains Toolbox, which I use to manage different versions of CLion, Android Studio and PyCharm - it's also developed in PyCharm!

Command Line Usage

NOTE: On Windows, due to OS and PyInstaller limitations, agstoolbox.exe doesn't work with command line arguments, so atbx.exe is for exclusive command line usage.

Code: bash

$ atbx --help
usage: atbx [-h] [-s {bash,zsh,tcsh}] [-v] {list,install,open,build,settings,export} ...

agstoolbox is an application to help manage AGS Editor versions.

positional arguments:
  {list,install,open,build,settings,export}
                        command
    list                lists things
    install             install tools
    open                open an editor or project
    build               build an ags project
    settings            modify or show settings
    export              export from ags project

optional arguments:
  -h, --help            show this help message and exit
  -s {bash,zsh,tcsh}    print shell completion script
  -v, --version         get software version.

Copyright 2023 Erico Vieira Porto, MIT.

As an example, a command line to force install the latest 3.6 AGS Editor, as a managed Editor is as follows

Code: bash

$ atbx install editor 3.6 -f
Will install managed AGS Editor release 3.6.0.47
 Downloading... 40475597/40475597 B |████████████████████████████████| AGS-3.6.0.47.zip
Extracting...
Installed release 3.6.0.47

The command line interface is working, but it is still quite limited, if you have more needs for it, please ask me!

Tab completion is also provided, the script for it can be generated with -s parameter, if you need help setting up just ask.


Experimentally, AGS Toolbox is also available on PyPI. Prefer the exe releases above for now, the PyPI releases are intended for uses of it's core parts and the atbx command line utility in continuous integration, the idea is if the pipeline has pip you can just use it to get agstoolbox and then atbx to get the editor setup in the pipeline - essentially two commands to setup AGS Editor in a CI environment.


AGS Toolbox is written in Python, so if you are interested in a new feature and want to contribute code, just ask me and I can explain the basics of it.

[Tarnos12]

Looks great! I've been using multiple ags versions lately and this will definitely help.
The fact that it knows which version the project used is great.

I will try it out later today, thanks.

[eri0o]

Awesome! Let me know how it goes! Any ideas of things to add feel free to add here.

When I started, I wrote the features I had in mind to pursue, but of course I expect these and priorities can be adjusted as other people use it: https://github.com/ericoporto/agstoolbox#desired-features

A warn, I have not tested with AGS 4, because it has no releases so far, I have no idea what will happen.

[Tarnos12]

Awesome! Let me know how it goes! Any ideas of things to add feel free to add here.

When I started, I wrote the features I had in mind to pursue, but of course I expect these and priorities can be adjusted as other people use it: https://github.com/ericoporto/agstoolbox#desired-features

A warn, I have not tested with AGS 4, because it has no releases so far, I have no idea what will happen.

Ah I use 4.0 too, will test after making a backup.

[eri0o]

Really minor release fixing a crash that happened when the Editor version was too short - happened with Editor 3.4.3.

Working on additional things now.

[eri0o]

Added a new 0.2.0 release

• running it a second time raises the AGS Toolbox window instead of opening a second instance
• added a setting to add itself to the Windows startup (it doesn't work on other OSes yet)

Note: if you use the startup with windows setting, I recommend to move the agstoolbox.exe file to a suitable place. I maintain my portable binaries under a directory I created in "C:\Users\MY_USER\software", if someone has a suggestion for a non-ProgramFiles location, mention yours.

Edit: Well, seconds after I realized I wasn't able to fetch 3.6.0 Release with this, and had to hack a better way to detect the AGS Release assets, so now it's a 0.2.1 release

Edit2: Minor adjustments to try to silently recover from invalid settings. Not sure it's enough yet.

Edit3: From 0.2.3 and onwards, right clicking on it on Explore you will be able to read which agstoolbox version you have.

[eri0o]

Hey, 0.4.0 version of agstoolbox.exe adds a small search bar! Not much you can do in it yet, but it's useful for filtering stuff!



Also check past improvements in the command line version atbx.exe.

[eri0o]

Found a bug that prevented agstoolbox to get the newest releases from github and fixed! new 0.4.1 release can properly fetch the recent 3.6.1 releases!

There is an issue that I don't know why it happens that it appears I can't build ags games through command line with atbx, the editor gives an error "Unable to set EXE name/description: LoadLibrary failed". This doesn't happen when using agstoolbox, if you right click a project and select the Quick build option. I don't know why this happens yet. 

Edit: tracked down the issue, it's due to pyinstaller using SetDllDirectory, detailed it here: https://github.com/ericoporto/agstoolbox/issues/31

The culprit appears to be SetDllDirectory is inherited by the child process.

[eri0o]

AGS Toolbox 0.4.2 released!

This fixes the longstanding issue that made AGS Editor give the "Unable to set EXE name/description: LoadLibrary failed" erro when building.

Now you can use both atbx build /my/project/path and also the Quick build functionality from agstoolbox interface without issues!

With this version, in theory, a simple github actions pipeline to build your ags game is now simply

Spoiler

Code: yaml

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: windows-latest

    steps:
      - uses: actions/checkout@v3

      - name: gets ags-toolbox
        run: |
          curl -Lo atbx.exe https://github.com/ericoporto/agstoolbox/releases/download/0.4.2/atbx.exe
          echo "${{github.workspace}}" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
          
      - name: install ags
        run: |
          atbx install editor -q test-game/
          
      - name: build game
        run: |
          atbx build test-game/

[close]

Unfortunately, this still won't work with current 3.6.1 (but it should work with non-beta versions). Next 3.6.1.13 will fix the issue of running agseditor in command line in a pipeline environment.

[eri0o]

Hey, AGS Toolbox 0.4.5 released! atbx.exe now can work with the newly AGS Editor v.3.6.1.14 in command line in GitHub Actions pipelines!

Code: yaml

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: windows-latest

    steps:
      - uses: actions/checkout@v3

      - name: gets ags-toolbox
        run: |
          curl -Lo atbx.exe https://github.com/ericoporto/agstoolbox/releases/download/0.4.5/atbx.exe
          echo "${{github.workspace}}" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
          
      - name: install ags
        run: |
          atbx install editor -q test-game/
          
      - name: build game
        run: |
          atbx build test-game/

Above is an actual GitHub Actions pipeline that works correctly for building ags games!

[eri0o]

new version 0.4.6 released, now atbx.exe can export script module from game projects in the command line!

You can do so like

Code: bash

/atbx.exe export script my_game my_module .

The idea here is you can use it to export a script module from a pipeline to push the module as a release artifact in a repository.

Code: bash

./atbx.exe export script --help
usage: atbx export script [-h] PROJECT_PATH MODULE_NAME OUT_DIR

positional arguments:
  PROJECT_PATH  path to the project with the module
  MODULE_NAME   name of the script module
  OUT_DIR       where to export the script module

optional arguments:
  -h, --help    show this help message and exit

[eri0o]

new 0.4.8 version!

Very minor update, noticed that Release Candidate versions of the AGS Editor were not possible to fetch and install, fixed that in this new release.

[eri0o]

new 0.4.9 version!

Very minor update again, noticed that AGS 4 releases of the AGS Editor were not possible to fetch and install, fixed that in this new release! 

[eri0o]

new 0.5.0 version!

If for some reason AGS Toolbox can't find the specified project when using the command line interface, it will now give better logging, hopefully making it easier to understand issues that may arise when using it in CI environments.

[eri0o]

new 0.5.1 version!

This version adds an experimental AGS Template export.

Code: ags

atbx export template ../ags-template-source/Tumbleweed Tumbleweed.agt .

essentially you use the export template command and subcommand, and then pass the directory with the game project, the name of the output file and the directory to put the file.

This is still not super well tested, it tries to mimick the behavior currently in the AGS Editor. The template export is reimplemented in python itself.

[eri0o]

I had released a 0.5.2 version that fixed a crashing bug and forgot to put it here!

Also when running in a totally clean PC I discovered my agstoolbox actually depends on VS2017 redistributable, I added a link to it in the first post - I guess either when I added VS itself or some Steam game that used redistributables it suddenly worked and I never noticed. Ah, the redistributable is only necessary for agstoolbox, the command line companion atbx does not require it.

(curiously I actually am building for windows using wine and docker but I had to steal some dlls from VS to make python work flawlessly, I guess I need to polish my python->exe building in Linux a little more)

[eri0o]

New AGS Toolbox 0.5.3 release, fixes not finding already installed 3.6.2 AGS Editor

[eri0o]

(minor improve over 0.5.4 in a specific error message from list releases that can happen if github api blocks the query for some reason)

New AGS Toolbox 0.5.5 now can use the /maketemplate command from the editor.

When using the export template command, use the -f or --force-editor flag to make it use the export template command from the editor instead of the self built mechanism in agstoolbox.

Code: bash

atbx export template -f ../../dkrey/ags_tumbleweed/ tumbleweed.agt ../

Will export the tumbleweed template as tumbleweed.agt on the ../ dir.

This will only work if the game project is using either Editor version 3.6.2.1 or above or if it's an ags4 project, version 4.0.0.9 or above. Additionally, the necessary editor version must also be installed - either from using the installer or as an agstoolbox managed editor.