Run your own Basic4GL code on Android

I’m very excited to announce the first Basic4GL Mobile release which you can actually run your own Basic4GL code.

Please keep in mind this is a very early development release. Don’t be surprised if a lot of BASIC commands haven’t been implemented yet.

You will need

  • An Android phone or tablet, running Android 4.4 (Kitkat) or later.
  • A Windows PC with Basic4GL installed (from the Basic4GL website).
  • The Basic4GL Mobile Android apk, download from here.
  • The Basic4GL Mobile Windows tools, download from here.
  • A way to copy files from your PC to your Android device.

For the last one, you can share a folder on your PC and pull files across using an Android file tool like “ES File Explorer”. Or you can setup a Google Drive/Dropbox folder and sync it with “FolderSync” or similar app (the “Lite” add-supported version works fine). I personally find the Google Drive/Dropbox option simpler once setup.

Getting started

Step 1 – Install the apk

First install the apk onto your phone/tablet (from here). Because this not a pristine validated app from the Play store you’ll need to enable “Allow installation of apps from unknown sources” (or similar) which is in Settings->Security (on my phone at least).

Once it’s installed, run it:Basic4glmobile2

 

It will tell you it cannot find the Basic4GL program.vm file.

More importantly it will tell you where you need to put the program.vm file (and any other files the program needs like image files).

For a lot of Android devices this will be:

/storage/emulated/0/basic4gl

But check what appears on screen.

Step 2 – Install the Windows tools

Next download and unzip the Windows tools (from here) onto your PC.

This will create two sub-folders: “Windows” and “Programs”

Inside the “Programs” sub-folder is where you create your Basic4GL program, compile it, test it and finally transfer it across to the Android device.

We’ll demonstrate by compiling the snakedemo.gb program and running it on Android, as follows:

  1. Open the “Programs” sub-folder in Windows explorer
  2. Drag the snakedemo.gb file onto the Compile.bat batch file.
  3. This invokes Compiler.exe in the “Windows” sub-folder to compile it, creating (or replacing) program.vm.
    “program.vm” contains all the op-codes and other data required to run the program on the Basic4GL virtual machine.
  4. Double click “Run.bat” to test run it using the Windows platform runtime.
  5. Copy “program.vm” to the basic4gl folder on Android.

There’s a bunch of different ways to do this and different apps you can use. I happen to use FolderSync Lite, because it’s the first one I happened to find that does the job,  but there’s bound to be others. To do this I dragged the Windows tools into my Google Drive folder, then used the FolderSync app to synchronise the “Programs” sub-folder to the “/storage/emulated/0/basic4gl” folder on my Android device (which could be a different folder on yours remember – check the original message).

Once that’s done, run Basic4GL on your Android device and play snake.

You may want to try AsteroidDemo2.gb as well. For this one you need to also transfer the “Data” sub-folder and all the image files it contains.

Running your own code

If you managed to get the above working, you can run your own code.

First you should copy “mobile.dll” and “msvcr120.dll” from the “Windows” sub-folder into your Basic4GL folder (where Basic4GL.exe lives). This adds a bunch of mobile commands to Basic4GL for things like handling touch screen events. Some of them don’t actually do anything when running in Basic4GL itself, but at least Basic4GL won’t stop with a syntax error when it sees them.

Note: Make sure to copy the files, not move them, because Compiler.exe needs them as well.

To access the commands in Basic4GL, click “File->Plug in Libraries…” and tick “Mobile.dll” which should now appear.

Save your program in the “Program” sub-folder. When you’re ready to try it on Android, follow the steps from before, to compile, test run and transfer it.

Limitations

You’ll probably run into the limitations pretty quickly. Basic4GL Mobile currently has implemented:

  • Standard BASIC functions (val, mid$, len etc)
  • Vector and matrix algebra
  • Text input/output
  • Sprites and tilemaps
  • PNG texture loading (using LoadTex. The old LoadTexture routines aren’t and won’t be implemented)
  • Mouse input (emulated on Android)
  • Timing (WaitTimer, SyncTimer etc)

There’s a bunch of things that haven’t been implemented yet, such as:

  • JPG image loading
  • Sound/music
  • Anything OpenGL
  • Anything in a plugin DLL

Basic4GL itself doesn’t know what’s implemented and what isn’t, so you’ll typically only know when you attempt to run it using the Windows platform runtime (by double clicking “Run.bat”).

This is one of the reasons for the Windows platform runtime, rather than just running everything in Basic4GL itself, as it has been developed in parallel with the Android platform runtime and has the exact same BASIC commands. If it runs on the Windows platform runtime then you can be reasonably confident that it will on Android. If not, it will tell you the BASIC function that it doesn’t recognise so you can update your program. The Windows platform runtime also has the same new character set that Android uses, and some basic touch input emulation using the mouse.

Mobile functions

This is as good a place as any to document the new mobile functions.

You can also see these in the Mobile.dll plugin “Functions” list in Basic4GL.

Miscellaneous

BackgroundColor(red,green,blue)

Sets the background colour. Because Basic4GL Mobile doesn’t support OpenGL commands you can’t use glClearColor(). red, green and blue are colour component intensities ranging from 0-255.

Platform info

PlatformName$()

Returns “Windows” on Windows and “Android” on Android.

PlatformIsMobile()

Returns false (0) on Windows and true (-1) on Android. The asteroid demo uses this to decide whether to display the touch screen controls for example.

PlatformIsDesktop()

Returns true (-1) on Windows and false (0) on Android.

Single touch

Note: This is a simplified interface if you’re only interested in single touch events.

Alternatively you may find it easier to use the standard Basic4GL mouse input commands. On Android the mouse is emulated based on touch screen events.

Touching()

Returns true (-1) if the user is currently touching the screen, or false (0) otherwise.

TouchX(), TouchY()

Returns the position of the touch. 0 is the left/top edge of the screen. 1 is the bottom/right edge.

If the user is not touching the screen, this returns the position that they were last touching.

TouchStartX(), TouchStartY()

Returns the position where the user started touching the screen.

Multi-touch

Multi-touch is handled by allocating a unique “touch ID” number to track every time the screen is touched. This number is used to lookup the information about that specific touch instance, such as it’s position, and whether it’s still touching.

NewTouchID()

Much like inkey$() returns keypresses, NewTouchID() returns touches.

Returns 0 if there are no new touches. Otherwise returns the “touch ID” of the new touch.

Touching(touchID)

Where touchID is a touch ID returned by NewTouchID. (Or TouchID() below).

Returns true (-1) if the user is currently touching the screen, or false (0) otherwise.

TouchX(touchID), TouchY(touchID)

Returns the position of the touch.

The application tracks all active touches, plus the last 16 that are no longer touching the screen, which should give the BASIC program enough time to read the position where the user’s finger was last before it was lifted from the screen.

TouchStartX(touchID), TouchStartY(touchID)

Returns the position where the touch started.

TouchCount()

Returns the number of active touches

TouchID(index)

Returns the touch ID of the indicated active touch.

index should be between 0 and TouchCount()-1 (inclusive).

Keyboard input

These are methods for controlling the on-screen keyboard.

The on-screen keyboard is managed automatically for the BASIC INPUT command (input “What is your name”; name$ etc), but you may want to bring it up explicitly if you are using Inkey$() to read key presses.

Note: On screen keyboard handling is not great on Android, mainly because the application cannot detect when the user closes the keyboard manually. It also cannot explicitly tell Android whether to show or hide it, only whether to “toggle” it. These functions therefore return whether the application thinks the on-screen keyboard should be visible, and will toggle the keyboard when it thinks it needs to be shown/hidden.

ShowKeyboard()

Shows the on-screen keyboard

HideKeyboard()

Hides the on-screen keyboard

IsKeyboardShowing()

Returns true (-1) if the on-screen keyboard is currently showing, or false (0) otherwise.

This entry was posted in Android, Basic4GL, Development blog and tagged , , , . Bookmark the permalink.