Introduction
The PocketBase extension for Clickteam Fusion provides an easy to use method to store and retrieve data in the open source PocketBase server project for your Clickteam Fusion games and apps.
Server Wrapper
If you're familiar with networking, you can run the included PocketBase server executable on your own computer using the PB_Server.exe wrapper. This wrapper will receive updates in the future as we add features to the extension, in order to assist with deploying custom server-side logic and other additions.
Hosting
You can also rent a server from us and let us worry about keeping it online and up to date. Details on this service are coming soon, check the forum posting below under Support.
System Requirements
This extension is tested only with Clickteam Fusion 2.5+. It supports only the Windows EXE deployment target at this time.
It may work with other versions of Clickteam Fusion but this is not guaranteed.
Installation
To install the extension, copy the contents of the ZIP file into the root of your Clickteam Fusion 2.5 installation directory.
After copying, the following files should exist inside your Clickteam Fusion 2.5 installation directory:
Data/Runtime/Unicode/PocketBase.mfx
Extensions/Unicode/PocketBase.mfx
Help/PocketBase.chm
Samples/PocketBase/PocketBase Example.mfa
Support
Please let us know if you have any issues. You can reach us at the following Clickteam forum posting:
https://community.clickteam.com/threads/110518-PocketBase-for-Clickteam-Fusion/
Actions
General
Global Expressions
SetDebugMode
Server
SetServerURL
SetServerPort
SetServerUsesSSL
User Account
Register
Login
Logout
Query
List/Search
View
Create/Update/Delete
Create
Update
Delete
Set String Field
Set Integer Field
Set Float Field
Clear Fields
Result Set
Loop Start
Loop Next
These expressions are updated by every action called.
· ErrorCode(): if the action failed, ErrorCode() is set to a unique error identifier; if the action succeeded ErrorCode() is set to 0. Note that it is best to only assume success when you receive a "Results" or "Success" condition trigger. Some error conditions may not be caught in some cases.
· ErrorMessage$(): if the action failed, ErrorMessage$() may contain a friendly error string.
Parameters
· New Debug Mode: integer; 1=on; 2=off
Sets a flag that turns on or off "debug mode". When debug mode is on, a popup dialog box shows each server response from PocketBase, which may aid in understanding the server communication flow.
Note that debugger information is always provided even when SetDebugMode is off. This provides detailed internal state of the extension, so it's always a good idea to add the extension to your debugger using the Debugger > Add object to debugger system action.
Expressions
· DebugMode(): set as specified
Parameters
· ServerURL: string
Sets the server URL used to connect to your PocketBase instance.
This should be in the following format, but see notes below:
http://servername
Notes:
1. This can include a port, but the port will be ignored and is controlled by SetServerPort
2. This can be either http or https, but the actual SSL flag is controlled by SetServerUsesSSL (for use with non-standard SSL ports)
Expressions
· ServerURL$(): set as specified
Parameters
· ServerPort: integer
Sets the actual port used to connect to the server in ServerURL.
This port must be either the PocketBase HTTP server port or a TLS server that forwards to PocketBase. If it is a TLS server, then use SetServerUsesSSL to indicate this.
Expressions
· ServerPort(): set as specified
Parameters
· Uses SSL: integer; 1=yes, 0=no
Indicates if the Server Port is a SSL/TLS server or not.
Set to 0 for local development.
Must be set to 1 for your live server otherwise your server is not secure!
Expressions
· ServerUsesSSL(): set as specified
Parameters
· Email: string
· Name: string
· Username: string
· Password: string
Registers a new user / player account on your server.
Expressions
· UserId$(): after successful Registration, UserId$() is set to the new user's ID.
Conditions
On Registration Success
On Registration Error
Parameters
· Identity: string
· Password: string
Logs in a user using either a username or password (passed in through the identity parameter) and a password.
Expressions
· Token$(): after successful Login, Token$() is set to the session token. This token is automatically included in all further Actions; on error value is cleared
· UserId$(): after successful Login, UserId$() is set to the logged in user's ID; on error value is cleared
· IsLoggedIn(): after successful Login, set to true; on error set to false
Conditions
· On Login Success
· On Login Error
Parameters
· None
Ends a user session by discarding the token value.
After Logout, only Register and Login are valid actions unless you have configured collections to allow public read access (not recommended, to reduce traffic to your server).
Expressions
· Token$(): value is cleared
· UserId$(): value is cleared
· IsLoggedIn(): set to false
Conditions
· On Logout Success
· On Logout Error
Parameters
· Collection: string; example: "gameSessions"
· Filter: string; example: "(id='abc' && created>'2022-01-01')"
· Sort: string; example: "-created,id" (this would sort first by created descending, then by id ascending)"
· Expand: string; example: "relField1,relField2.subRelField"
Fetches a list of items in a particular collection, optionally filtering the results returned and optionally expanding related items.
Expanded related items are returned in a subkey within each object called expand. So to access those fields (via ItemField$(), ItemFieldInt() and ItemFieldFloat()) you need to use JSON Pointer syntax. See the ItemField$() expression for more information.
Conditions
· On New Result Set
· On Query Error
Parameters
· Collection: string
· Id: string
· Expand: string; example: "relField1,relField2.subRelField"
Fetches a single item from a particular collection by id, optionally expanding related items.
See List/Search for details on how the Expand parameter works.
Expressions
· ItemField$(): will return value for the given field for the item fetched
· ItemFieldInt(): will return value for the given field for the item fetched
· ItemFieldFloat(): will return value for the given field for the item fetched
Conditions
· On View Results
· On View Error
Parameters
· Collection: string
· [ object field/values set via Set String Field, Set Integer Field, Set Float Field ]
Creates a new item in a collection.
Expressions
· CreatedItemId$(): set to the new item's 15-character string ID
Conditions
· On Create Success
· On Create Error
Parameters
· Collection: string
· Id: string
· [ object field/values set via Set String Field, Set Integer Field, Set Float Field ]
Updates an existing item in a collection.
You only need to specify the fields that you actually want to update, you should generally avoid sending unchanged fields whenever possible to reduce bandwidth and to avoid overwriting possible changes made by other instances of your client code.
Conditions
· On Update Success
· On Update Error
Parameters
· Collection: string
· Id: string
Deletes an existing item from a collection.
Conditions
· On Delete Success
· On Delete Error
Parameters
· Field Name: string
· Field Value: string
Sets a field's String value by name to be used in the Create and Update actions.
Parameters
· Field Name: string
· Field Value: integer
Sets a field's Integer value by name to be used in the Create and Update actions.
Parameters
· Field Name: string
· Field Value: field
Sets a field's Float value by name to be used in the Create and Update actions.
Parameters
· None
Removes all fields previously set via the Set String Field, Set Integer Field and Set Float Field actions, preparing the internal list of fields for a new object to be created or updated.
Parameters
· None
Starts a loop over the result set returned by the List/Search action.
The current item/row is set to the first item in the result list, and the On Row Change condition is triggered.
Expressions
· ItemNumber(): set to 0
· IsLastItem(): to to true if there are no items in the list, false otherwise
Conditions
· On Row Change: only called if there are rows in the result set, otherwise the action is ignored
Parameters
· None
Advances the current item number to the next item in the result list, and triggers the On Row Change condition.
Expressions
· ItemNumber(): set to the next index in the result set, zero based
· IsLastItem(): to to true if this is the last item in the result set, false otherwise
· ItemField$(): will return value for the given field for the next item
· ItemFieldInt(): will return value for the given field for the next item
· ItemFieldFloat(): will return value for the given field for the next item
Conditions
· On Row Change: only called if there are more rows in the result set, otherwise the action is ignored
Conditions
General
General Information
User Account
On Registration Success
On Registration Error
On Login Success
On Login Error
On Logout Success
On Logout Error
Query
On New Result Set
On Query Error
Create/Update/Delete
On Create Success
On Create Error
On Update Success
On Update Error
On Delete Success
On Delete Error
On View Results
On View Error
Result Set
On Row Change
Conditions in the PocketBase for CTF extension are only triggered as a result of an API call to a PocketBase server, triggered from your event code, or as a result of an internal operation triggered from your event code. Conditions will never fire spontaneously without an Action you have triggered first being called.
Most of the conditions listed above are not separately documented since their name provides complete information on how they function -- the Success condition for Registration is called when the Register action succeed, the Error condition is called when it fails.
The only exceptions to this naming convention are:
· On New Result Set -- called when a List/Search action returns data successfully.
· On Row Change -- called when either of the Loop Start or Loop Next actions successfully advance the ItemNumber to the next row in a Result Set. These actions do not have an Error condition.
This condition is called when either the Loop Start action moves the internal item cursor (represented by ItemNumber() expression) to the first row (row 0), or when the Loop Next action advances the cursor to the next row in a Result Set. These actions work with a Result Set returned by the List/Search action, and are how you can easily loop over the results.
Each time On Row Change is triggered, perform the action you would like to take on the results (storing them in another location, loading active objects, writing to a list, etc.), then call Loop Next at the end of this condition to advance to the next row, where the process repeats.
Tracking which collection results are from
If you fetch from different Collections with the same PocketBase object, you need to keep track of which one you have fetched using your own variable. This variable can be an additional limiting condition for the On Row Change condition, so that you can have separate events defined for each kind of loop.
Multiple Concurrent Loops
There is only one active cursor / loop allowed per PocketBase object. If you want to loop over more than one result set at the same time, they need to have been fetched by separate objects.
Remember in this case that each object must be logged in and will have it's own UserToken$() value.
Expressions
See the Actions documentation for more details on when each expression is updated. By default all of these expressions are blank or 0 (depending on type), until the corresponding action has been called.
|
Expression |
Type |
|
ServerURL$() |
string |
|
IsLoggedIn() |
integer (1=true, 0=false) |
|
Token$() |
string |
|
UserId$() |
string |
|
ErrorMessage$() |
string |
|
ErrorCode() |
integer |
|
DebugMode() |
integer |
|
ItemField$(<field>) |
string |
|
ItemFieldInt(<field>) |
integer |
|
ItemFieldFloat(<field>) |
float |
|
IsLastItem() |
integer (1=true, 0=false) |
|
ItemNumber() |
integer (0 based) |
|
CreatedItemId$() |
string (15 characters) |
|
ServerUsesSSL() |
integer (1=true, 0=false) |