View source

class FlxGameJolt

package flixel.addons.api

Similar to FlxKongregate, this allows access to the GameJolt API. Based loosely on the AS3 version by SumYungGai with many changes.

@:file("myKey.privatekey") class MyKey extends ByteArray { } to embed that file's data as a ByteArray. If your game is embedded as Flash on GameJolt's site, or run via Quick Play, you do not need to get the user name and token; this will be done automatically. Otherwise, you will need to retrieve the user name and token (possibly via an input box prompt). Then, verify this data via the following method: var bytearray = new MyKey(); // This will load your private key data as a ByteArray. var keystring = bytearray.readUTFBytes(bytearray.length); // This converts the ByteArray to a string. var gameid = 1; // Replace "1" with your game ID, visible if you go to https://gamejolt.com/dashboard/ -> Click on your game under "Manage Games" -> Click on "Achievements" in the menu. * FlxGameJolt.init(gameid, keystring); // Use this if your game is embedded as Flash on GameJolt's site, or run via Quick Play.

See also:

Static variables

@:value(0)staticinlineread onlyHASH_MD5:Int = 0

Hash types for the cryptography function. Use this or HASH_SHA1 for encryptURL(). MD5 is used by default.

@:value(1)staticinlineread onlyHASH_SHA1:Int = 1

Hash types for the cryptography function. Use this or HASH_MD5 for encryptURL(). MD5 is used by default.

@:value(-2)staticinlineread onlyTROPHIES_ACHIEVED:Int = -2

Trophy data return type, will return only unlocked trophies. As an alternative, can just pass in the ID of the trophy to see if it's unlocked.

@:value(-1)staticinlineread onlyTROPHIES_MISSING:Int = -1

Trophy data return type, will return only non-unlocked trophies. As an alternative, can just pass in the ID of the trophy to see if it's unlocked.

@:value(HASH_MD5)statichashType:Int = HASH_MD5

The hash type to be used for private key encryption. Set to FlxGameJolt.HASH_MD5 or FlxGameJolt.HASH_SHA1. Default is MD5. See https://gamejolt.com/api/doc/game/ section "Signature".

staticread onlyinitialized:Bool

Whether or not the API has been fully initialized by passing game id, private key, and authenticating user name and token.

staticread onlyisEmbeddedFlash:Bool

An alternative to running authUser() and hoping for the best; this will tell you if your game was run as an embedded Flash on GameJolt that has user name and token data already. Does NOT authenticate the user data!

Returns:

True if it's an embedded SWF with user name and token available, false otherwise.

staticread onlyisQuickPlay:Bool

An alternative to running authUser() and hoping for the best; this will tell you if your game was run via Quick Play, and user name and token is available. Does NOT authenticate the user data!

Returns:

True if this was run via Quick Play with user name and token available, false otherwise.

staticread onlyusername:String

The user's GameJolt user name. Only works if you've called authUser() and/or init(), otherwise will return "No user".

staticread onlyusertoken:String

The user's GameJolt user token. Only works if you've called authUser() and/or init(), otherwise will return "No token". Generally you should not need to mess with this.

@:value(false)staticverbose:Bool = false

Whether or not to log the URL that is contacted and messages returned from GameJolt. Useful if you're not getting the right data back. Only works in debug mode.

Static methods

@:value({ AllowGuest : false })staticaddScore(Score:String, Sort:Float, ?TableID:Int, AllowGuest:Bool = false, ?GuestName:String, ?ExtraData:String, ?Callback:Dynamic):Void

Set a new high score, either globally or for this particular user. Requires game initialization. If user data is not authenticated, GuestName is required. Please note: On native platforms, having spaces in your Sort, GuestName, or ExtraData values will break this function.

Parameters:

Score

A string representation of the score, such as "234 Jumps".

Sort

A numerical representation of the score, such as 234. Used for sorting of data.

TableID

Optional: the ID of the table you'd lke to send data to. If null, score will be sent to the primary high score table. Ignored if zero.

AllowGuest

Whether or not to allow guest scores. If true is passed, and user data is not present (i.e. authUser() was not successful), GuestName will be used if present. If false, the score will only be added if user data is authenticated.

GuestName

The guest name to use, if AllowGuest is true. Ignored otherwise, or if "".

ExtraData

Optional extra data associated with the score, which will NOT be visible on the site but can be retrieved by the API. Ignored if "".

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

staticaddTrophy(TrophyID:Int, ?Callback:Dynamic):Void

Unlock a trophy for this user. Requires user authentication.

Parameters:

TrophyID

The unique ID number for this trophy. Can be seen at https://gamejolt.com/dashboard/developer/games/achievements// in the right-hand column.

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

staticauthUser(?UserName:String, ?UserToken:String, ?Callback:Dynamic):Void

Verify user data. Must be called before any user-specific functions, and after init(). Will set initialized to true if successful.

Parameters:

UserName

A user name. Leave null to automatically pull user data (only works for embedded Flash on GameJolt or Quick Play). Usernames can only have letters, numbers, hyphens (-) and underscores (_), and must be 3-30 characters long.

UserToken

A user token. Players enter this instead of a password to enable highscores, trophies, etc. Leave null to automatically pull user data (only works for embedded Flash on GameJolt or Quick Play). User tokens can only have letters and numbers, and must be 4-30 characters long.

Callback

An optional callback function. Will return true if authentication was successful, false otherwise.

See also:

staticcloseSession(?Callback:Dynamic):Void

Close the current session. Requires user data authentication.

Parameters:

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

staticfetchAvatarImage(?Callback:BitmapData ‑> Void):Void

An easy-to-use function that returns the user's avatar image as BitmapData. Requires that you've authenticated the user's data. All user images will be 60px by 60px.

Parameters:

Callback

An optional callback function. Must take a BitmapData object as a parameter.

@:value({ User : true })staticfetchData(Key:String, User:Bool = true, ?Callback:Dynamic):Void

Get data from the remote data store.

Parameters:

Key

The key for the data to retrieve.

User

Whether or not to get the data associated with this user. True by default.

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

staticfetchScore(?Limit:Int, ?TableID:Int, ?Callback:Dynamic):Void

Retrieve the high scores from this game's remote data. If not authenticated, leaving Limit null will still return the top ten scores. Requires initialization.

Parameters:

Limit

The maximum number of scores to retrieve. If blank to retrieve only this user's scores.

TableID

The ID of the table you want to pull data from. Leave blank to fetch from the primary score table.

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

@:value({ DataType : 0 })staticfetchTrophy(DataType:Int = 0, ?Callback:Dynamic):Void

Retrieve trophy data. Requires user authentication.

Parameters:

DataType

Pass FlxGameJolt.TROPHIES_MISSING or FlxGameJolt.TROPHIES_ACHIEVED to get the trophies this user is missing or already has, respectively. Or, pass in a trophy ID # to see if this user has that trophy or not. If unused or zero, will return all trophies.

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

staticfetchTrophyImage(ID:Int, ?Callback:BitmapData ‑> Void):Void

An easy-to-use function that returns the image associated with a trophy as BitmapData. All trophy images will be 75px by 75px.

Parameters:

ID

The ID of the trophy whose image you want to get.

Callback

An optional callback function. Must take a BitmapData object as a parameter.

staticfetchUser(?UserID:Int, ?UserName:String, ?UserIDs:Array<Int>, ?Callback:Dynamic):Void

Fetch user data. Pass UserID to get user name, pass UserName to get UserID, or pass multiple UserIDs to get multiple usernames.

Parameters:

UserID

An integer user ID value. If this is passed, UserName and UserIDs are ignored. Pass 0 to ignore.

UserName

A string user name. If this is passed, UserIDs is ignored. Pass "" or nothing to ignore. Usernames can only have letters, numbers, hyphens (-) and underscores (_), and must be 3-30 characters long.

UserIDs

An array of integers representing user IDs. Pass [] or nothing to ignore.

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

@:value({ User : true })staticgetAllKeys(User:Bool = true, ?Callback:Dynamic):Void

Get all keys in the data store.

Parameters:

User

Whether or not to get the keys associated with this user. True by default.

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

staticgetTables(?Callback:Dynamic):Void

Retrieve a list of high score tables for this game.

Parameters:

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

@:value({ AutoAuth : false })staticinit(GameID:Int, PrivateKey:String, AutoAuth:Bool = false, ?UserName:String, ?UserToken:String, ?Callback:Dynamic):Void

Initialize this class by storing the GameID and private key. You must call this function first for many of the other functions to work. To enable user-specific functions, call authUser() afterward, or set AutoAuth to true.

Parameters:

GameID

The unique game ID associated with this game on GameJolt. You must create a game profile on GameJolt to get this number.

PrivateKey

Your private key. You must have a developer account on GameJolt to have this number. Do NOT store this as plaintext in your game!

AutoAuth

Call authUser after init() has run to authenticate user data.

UserName

The username to authenticate, if AutoAuth is true. If you set AutoAuth to true but don't put a value here, FlxGameJolt will attempt to get the user data automatically, which will only work for Flash embedded on GameJolt, or games run via Quick Play.

UserToken

The user token to authenticate, if AutoAuth is true. If you set AutoAuth to true but don't put a value here, FlxGameJolt will attempt to get the user data automatically, which will only work for Flash embedded on GameJolt, or games run via Quick Play.

Callback

An optional callback function, which is only used if AutoAuth is set to true. Will return true if authentication was successful, false otherwise.

staticopenSession(?Callback:Dynamic):Void

Begin a new session. Sessions that are not pinged at most every 120 seconds will be closed. Requires user authentication.

Parameters:

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

@:value({ Active : true })staticpingSession(Active:Bool = true, ?Callback:Dynamic):Void

Ping the current session. The API states that a session will be closed after 120 seconds without a ping, and recommends pinging every 30 seconds or so. Requires user authentication.

Parameters:

Active

Leave true to set the session to active, or set to false to set the session to idle.

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

@:value({ User : true })staticremoveData(Key:String, User:Bool = true, ?Callback:Dynamic):Void

Remove data from the remote data store.

Parameters:

Key

The key for the data to remove.

User

Whether or not to remove the data associated with this user. True by default.

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

staticresetUser(UserName:String, UserToken:String, ?Callback:Dynamic):Void

Function to authenticate a new user, to be used when a user has already been authenticated but you'd like to authenticate a new one. If you just try to run authUser after a user has been authenticated, it will fail.

Parameters:

UserName

The user's name.

UserToken

The user's token.

Callback

An optional callback function. Will return true if authentication was successful, false otherwise.

@:value({ User : true })staticsetData(Key:String, Value:String, User:Bool = true, ?Callback:Dynamic):Void

Set data in the remote data store. Please note: On native platforms, having spaces in your Value parameter will break this function.

Parameters:

Key

The key for this data.

Value

The key value.

User

Whether or not to associate this with this user. True by default.

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also:

@:value({ User : true })staticupdateData(Key:String, Operation:String, Value:String, User:Bool = true, ?Callback:Dynamic):Void

Update data which is in the data store. Please note: On native platforms, having spaces in your Value parameter will break this function.

Parameters:

Key

The key of the data you'd like to manipulate.

Operation

The type of operation. Acceptable values: "add", "subtract", "multiply", "divide", "append", "prepend". The former four are only valid on numerical values, the latter two only on strings.

Value

The value that you'd like to work with on the data store.

User

Whether or not to work with the data associated with this user.

Callback

An optional callback function. Will return a Map whose keys and values are equivalent to the key-value pairs returned by GameJolt.

See also: