Workspaces - efroemling/ballistica GitHub Wiki

Workspaces is one of the main new features in Ballistica/BombSquad 1.7. Workspaces are virtual directories associated with your game account where you can place mod scripts. These directories will then be automatically synced to any device where you sign in, allowing you to set up sets of mods that you can easily use anywhere the game runs.

• Key Features
• Hello World Example
• Offline Editing With bacloud

• Simplicity. Workspaces allow you to get started writing mods using nothing but a copy of the game and a web browser.
• Offline support. The bacloud tool can be used to sync workspaces between your account and your computer, allowing you to use your own code editing environments, manage your workspaces with git, etc.
• Identical behavior on all platforms. No more learning platform-specific directories and behaviors when trying to install mods.
• A solid foundation to build on. In the future it could be possible to automatically host cloud servers using workspaces, easily run checks and tests on workspace code, or easily share workspaces with friends or the world.

Let's start with the standard print something on the screen tutorial.

1. To use workspaces, you will need a 'V2' game account, also called a 'Ballistica Account' or a 'BombSquad Account'. In the future, some existing account types such as Google Play and Game Center will be updated to support V2 features, but for now you may need to create a fresh account. Go to https://ballistica.net to create an account using an email address and password. You can then use that account to sign in on any platform (as long as you are running version 1.7.4 or newer). Unlike with old 'device accounts', you will never lose your account if you lose your device or reinstall your OS.
   

2. Once you've created a V2 account, launch any copy of the game (version 1.7.4 or newer) and sign in with that account in the Account section.
   

3. Now that we're signed in to our shiny new V2 account in-game, let's create our workspace. Close the game and go back to https://ballistica.net. You are probably still signed in with your new account there, but sign in again if not. Once you are signed in, go to the 'workspaces' page, create a new workspace, and set it as the active one for your account.
   

4. Now launch the game. If everything is set up correctly you should see a "Workspace1 activated" message as the game logs us in and fetches our workspace.
   
   Success! The game is now syncing our workspace to itself every time it launches, meaning we can edit the workspace online and simply re-launch the game to see our changes.

5. Now let's add some code to our workspace so it actually does something. Close the game again, go back to the web browser, navigate to the workspace we just created, and tap "Add Files/Folders" which should give us some options for things to add to the workspace.
   

6. Let's create a plugin. Plugins are special classes that can be automatically detected and loaded by the game, which provides a convenient launching point for mods to do whatever they want to do. So look for the plugin template option, give it a name like myplugin.py, and hit 'create'.
   

7. You should now see that there is a single file in your workspace. Poke 'Edit' and let's take a look at it.
   
   Aaaaand here's the code for our shiny new plugin. You can see it is just a simple class that prints a message to the screen when the app reaches the 'running' state. There are also a few ba_meta tags which are used by the game to locate things like plugins.

8. Now launch the game again. You should get the same 'Workspace1 activated.' message, except this time the game should follow it up with a 'New plugin(s) found' message moments later when it finishes scanning for plugins and finds our new one. Whenever the game finds new plugins, it sets them to be active, but they will not actually run until the next time the game launches.
   
   NOTE: Starting in version 1.7.6, newly detected plugins will be activated immediately; no restart required. So you may not need to restart here.
   

9. So, now that our new plugin has been detected, let's restart the game one more time and see what we get...
   
   Hey look, it's our plugin!!!

10. As a side note, it is possible to deactivate plugins from Settings -> Advanced -> Plugins if you want to turn individual ones off later without deleting them from your workspace.
    

Well, that's pretty much it for the basics. Now we can edit code in our workspace and re-launch the game to run it. To demonstrate this, try changing the ba.screenmessage() call to say something different. Press 'Save' in the editor (or Command-S / Control-S) and then re-launch the game and you should see your newly edited message.

Once you've got the basics down, the next step is to actually write some fun mod code, but that will be covered elsewhere...

While the online workspace editor is convenient for simple modding purposes, you may prefer working on a computer so you can use a fancy code editor, manage your workspace code via git, etc. That's where bacloud comes in.

bacloud is a command line tool included as part of this repo which lets you interact with Ballistica cloud functionality. It is a pretty simple Python script that makes web requests to ballistica.net on your behalf. To use it, you will need to go through at least part of the Getting Started process so that you have the correct version of Python and some pip modules installed.

Once your environment is set up correctly, you should be able to open a terminal, cd to your copy of this repo, type tools/bacloud and press return, and get something like this:

As you can see, bacloud provides a simple hierarchy of groups and commands. One of those is workspace. To learn more, we can run tools/bacloud workspace which will show us this:

You can see there are a few workspace commands we can use for listing, getting, or putting workspaces. So, for example, to list our workspaces, we would run tools/bacloud workspace list. However, if we try that now, we'll see one big problem: the bacloud tool is not logged in.

Let's fix that. We can see in the top level command list above there is a signin command. Let's do that. Run tools/bacloud signin and it should pop up a web browser allowing us to sign in with our V2 account, similar to how BombSquad itself works. Once we're logged in, we should be able to run tools/bacloud workspace list again and this time see some results (assuming we have created one or more workspaces already on ballistica.net):

From here it is pretty simple. We can use the get or put commands to quickly sync workspaces back and forth between our computer and the cloud. So let's try that.

Let's pull our workspace down to our Desktop folder. To do this, we run tools/bacloud workspace get Workspace1 ~/Desktop

We should now have a copy of the workspace on our computer. Let's make some change to it by editing the local files (perhaps edit the screenmessage() string again) and then push the whole thing back to the cloud by running tools/bacloud workspace put ~/Desktop/Workspace1

Now if we launch the game we should see the updated screenmessage (provided Workspace1 is active). We should also be able to go to the online code editor and see the change we just pushed.

That's pretty much it! You can now work purely offline and just run a bacloud workspace put command whenever we want to see your changes in the game, or whatever sort of workflow works for you.

Enjoy!

---

<< Knowledge Nuggets       Python Overview >>