Skip to content

Commit

Permalink
Rename core interface methods to clarify their purposes (issue #15)
Browse files Browse the repository at this point in the history
  • Loading branch information
@MrStahlfelge
MrStahlfelge committed Aug 29, 2017
1 parent ec91317 commit 55c705c
Show file tree
Hide file tree
Showing 13 changed files with 242 additions and 145 deletions.
50 changes: 34 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Framework and implementations for using Game Services (BaaS) with libGDX.
* [GameJolt](https://github.com/MrStahlfelge/gdx-gamesvcs/wiki/GameJolt) (all platforms)
* [Newgrounds](https://github.com/MrStahlfelge/gdx-gamesvcs/wiki/Newgrounds) (HTML5)

Further contributes are very welcome! Very wanted: Steam, Apple GameCenter. :-)
Further contributes are very welcome! Very wanted: Steam, Apple GameCenter, Play Games HTML5. :-)

## Motivation

Expand Down Expand Up @@ -45,7 +45,7 @@ into your project by just adding the dependencies to your `build.gradle` file.
Define the version of this API right after the gdxVersion:

gdxVersion = '1.9.6'
gamesvcsVersion = '0.1.1'
gamesvcsVersion = '0.2.0-SNAPSHOT' // '0.1.2' for using stable version

Core:

Expand All @@ -69,10 +69,12 @@ To build from source, clone or download this repository, then open it in Android
See `build.gradle` file for current version to use in your dependencies.

## Usage
**This documentation is only valid for v0.2. If you want to use older version v0.1, please see documentation on release/0.1.x branch.**

A good library should be easy to use (let me know what you think of this lib).
When updating from v0.1 to v0.2, please note that main interface methods were
renamed to clarify their purpose. See [issue #15](https://github.com/MrStahlfelge/gdx-gamesvcs/issues/15) for the full list.

### Connecting to the game service
### Initializing the game service client

You should be fine by adding the following lines to your game in order to connect to the service:

Expand All @@ -91,22 +93,22 @@ Main game class:
gsClient.setListener(this);

// establish a connection to the game service without error messages or login screens
gsClient.connect(true);
gsClient.resumeSession();
}

@Override
public void pause() {
super.pause();

gsClient.disconnect();
gsClient.pauseSession();
}

@Override
public void resume() {
super.resume();

gsClient.connect(true);
gsClient.resumeSession();
}

In the launcher class you instantiate and initialize the GameServiceClient you really want to use:
Expand All @@ -118,7 +120,11 @@ In the launcher class you instantiate and initialize the GameServiceClient you r
myGdxGame.gsClient = gsClient;


Check for `gsClient.isConnected()` if you successfully established a connection, or set a listeneder and wait for the call to `gsConnected`.
If you want to know if you established a connection to a user session, you can use
`gsClient.isSessionActive()`, or set a listener and wait for the call to
`gsOnSessionActive()`. You don't need to check if a user session is active for
submitting scores, events and unlocking achievements, as some game services allow anonymous
or guest submits. The API client implementations do all needed checks.

### Submitting events and scores, unlocking achievements

Expand All @@ -132,35 +138,47 @@ Events are interesting for you as a developer.

gsClient.submitEvent(eventId, 1);

Please note: It depends of the game services which calls are allowed for unauthenticated users. The API client implementations deal with that so you don't have to.
Please note: It depends of the game services which calls can be processed without a user session. The API client implementations deal with that so you don't have to.

### Cloud save

Not every game service and client implementation supports cloud save, so you must check the availability by checking

if (gsClient.supportsCloudGameState() != CloudSaveCapability.NotSupported)
if (gsClient.isFeatureSupported(GameServiceFeature.GameStateStorage))

If you ensured that cloud save feature is enabled, use this methods to invoke it:
If you ensured that cloud save feature is available, use this methods to invoke it:

gsClient.loadGameState(fileId);
gsClient.loadGameState(fileId, new ILoadGameStateResponseListener() {...});

gsClient.saveGameState(fileId, gameState, progressValue);
gsClient.saveGameState(fileId, gameState, progressValue,
new ISaveGameStateResponseListener() {...});

The methods perform an ansynchronous operation and call your listener afterwards.


### Fetching scores and achievement status

The interface provides a method for open up an API's default leaderboard or achievmeent UI:
The interface provides a method for open up an API's default leaderboard or achievment UI:

gsClient.providesAchievementsUI();
gsClient.showAchievements();
// same for leaderboards

At the moment, such a default UI is only provided by Google Play Games and GameCircle on Android.
At the moment, such a default UI is only provided by Google Play Games and GameCircle on Android,
so you need to check with `gsClient.isFeatureSupported()` before calling.

Fetching scores and achievement status to show in your own UI is work in progress in v0.2.x.
Fetching scores and achievement status to show in your own UI can be done by calling

gsClient.fetchLeaderboardEntries()
gsClient.fetchAchievements()

after checking

gsClient.isFeatureSupported(IGameServiceClient.GameServiceFeature.FetchLeaderBoardEntries)
gsClient.isFeatureSupported(IGameServiceClient.GameServiceFeature.FetchAchievements))

Your given listener will be called with a list of achievement or leader board
entries in response. Please refer to the JavaDocs or the demo application for more information.

## Updates & News
Follow me to receive release updates about this
Expand Down
51 changes: 30 additions & 21 deletions android-amazongc/src/de/golfgl/gdxgamesvcs/GameCircleClient.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,9 +100,9 @@ protected void agcServiceNotReady(AmazonGamesStatus amazonGamesStatus) {
isConnectionPending = false;
isConnected = false;
if (gsListener != null) {
gsListener.gsDisconnected();
gsListener.gsOnSessionInactive();
if (!autoStartSignInFlow)
gsListener.gsErrorMsg(IGameServiceListener.GsErrorType.errorLoginFailed,
gsListener.gsShowErrorToUser(IGameServiceListener.GsErrorType.errorLoginFailed,
amazonGamesStatus.name(), null);
}
}
Expand All @@ -122,7 +122,7 @@ public void onComplete(final RequestPlayerResponse response) {
if (!response.isError()) {
cachedPlayerAlias = response.getPlayer().getAlias();
if (gsListener != null)
gsListener.gsConnected();
gsListener.gsOnSessionActive();
}
}
}
Expand Down Expand Up @@ -154,7 +154,7 @@ public void onSyncFailed(FailReason reason) {


if (gsListener != null)
gsListener.gsConnected();
gsListener.gsOnSessionActive();

}

Expand All @@ -169,11 +169,20 @@ public void setListener(IGameServiceListener gsListener) {
}

@Override
public boolean resumeSession() {
return connect(true);
}

@Override
public boolean logIn() {
return connect(false);
}

public boolean connect(boolean silent) {
if (myContext == null || agsFeatures == null)
throw new IllegalStateException("Call initialize() before connecting");

if (isConnected())
if (isSessionActive())
return true;

isConnectionPending = true;
Expand All @@ -197,37 +206,37 @@ public void onServiceNotReady(AmazonGamesStatus amazonGamesStatus) {
}

@Override
public void disconnect() {
if (isConnected()) {
public void pauseSession() {
if (isSessionActive()) {
Gdx.app.log(GS_CLIENT_ID, "Disconnecting from GameCircle");

AmazonGamesClient.release();
isConnected = false;

if (gsListener != null)
gsListener.gsDisconnected();
gsListener.gsOnSessionInactive();
}
}

@Override
public void logOff() {
if (isConnected()) {
if (isSessionActive()) {
Gdx.app.log(GS_CLIENT_ID, "Shutting down GameCircle client");

AmazonGamesClient.shutdown();
cachedPlayerAlias = null;
if (gsListener != null)
gsListener.gsDisconnected();
gsListener.gsOnSessionInactive();
}
}

@Override
public String getPlayerDisplayName() {
return (isConnected() ? cachedPlayerAlias : null);
return (isSessionActive() ? cachedPlayerAlias : null);
}

@Override
public boolean isConnected() {
public boolean isSessionActive() {
return agsClient != null && AmazonGamesClient.isInitialized() && isConnected && !isConnectionPending;
}

Expand All @@ -238,21 +247,21 @@ public boolean isConnectionPending() {

@Override
public void showLeaderboards(String leaderBoardId) throws GameServiceException {
if (isConnected()) {
if (isSessionActive()) {
if (leaderBoardId != null)
agsClient.getLeaderboardsClient().showLeaderboardOverlay(leaderBoardId);
else
agsClient.getLeaderboardsClient().showLeaderboardsOverlay();
} else
throw new GameServiceException.NotConnectedException();
throw new GameServiceException.NoSessionException();
}

@Override
public void showAchievements() throws GameServiceException {
if (isConnected())
if (isSessionActive())
agsClient.getAchievementsClient().showAchievementsOverlay();
else
throw new GameServiceException.NotConnectedException();
throw new GameServiceException.NoSessionException();
}

@Override
Expand All @@ -263,7 +272,7 @@ public boolean fetchAchievements(IFetchAchievementsResponseListener callback) {

@Override
public boolean submitToLeaderboard(String leaderboardId, long score, String tag) {
if (!leaderboardsEnabled || !isConnected())
if (!leaderboardsEnabled || !isSessionActive())
return false;

agsClient.getLeaderboardsClient().submitScore(leaderboardId, score);
Expand All @@ -290,7 +299,7 @@ public boolean unlockAchievement(String achievementId) {

@Override
public boolean incrementAchievement(String achievementId, int incNum, float completionPercentage) {
if (!achievementsEnabled || !isConnected())
if (!achievementsEnabled || !isSessionActive())
return false;

agsClient.getAchievementsClient().updateProgress(achievementId, completionPercentage * 100);
Expand All @@ -309,7 +318,7 @@ public void saveGameState(String fileId, byte[] gameState, long progressValue,

public Boolean saveGameStateSync(String id, byte[] gameState, long progressValue,
ISaveGameStateResponseListener listener) {
if (!isConnected() || !whisperSyncEnabled)
if (!isSessionActive() || !whisperSyncEnabled)
return false;

GameDataMap gameDataMap = AmazonGamesClient.getWhispersyncClient().getGameData();
Expand Down Expand Up @@ -337,7 +346,7 @@ public void loadGameState(final String fileId, final ILoadGameStateResponseListe
if (!whisperSyncEnabled)
throw new UnsupportedOperationException();

if (!isConnected()) {
if (!isSessionActive()) {
listener.gsGameStateLoaded(null);
return;
}
Expand Down Expand Up @@ -380,7 +389,7 @@ public boolean isFeatureSupported(GameServiceFeature feature) {
}

protected boolean loadGameStateSync(String fileId, ILoadGameStateResponseListener listener) {
if (!isConnected() || !whisperSyncEnabled) {
if (!isSessionActive() || !whisperSyncEnabled) {
listener.gsGameStateLoaded(null);
return false;
}
Expand Down
Loading

0 comments on commit 55c705c

Please sign in to comment.