Taploka

https://taploka.hyuu.dev/docs
Admin
Taploka is an arcade gaming platform and deployment runtime that enables developers to publish,...
Tokens:6,311
Snippets:83
Trust Score:4.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Minimal SDK integration example

Source: https://taploka.hyuu.dev/docs/game-sdk

A complete example showing initialization, loading state, tracking events, and submitting scores upon game over.

```html
<script>
  (async () => {
    const session = await taploka.ready();
    const state = await taploka.load() ?? { level: 1 };

    startGame(state, {
      onLevelEnd: (level) => taploka.track('level_end', { level }),
      onGameOver: async (score) => {
        await taploka.submitScore(score);
        await taploka.save({ level: state.level });
      },
    });
  })();
</script>
```

--------------------------------

### Publish Bundle from CI

Source: https://taploka.hyuu.dev/docs/harness-api

Example command to publish a bundle using curl in a CI environment.

```bash
curl -sS -X POST "$TAPLOKA_URL/api/v1/harness/bundles" \
  -H "Authorization: Bearer $TAPLOKA_KEY" \
  -H "Accept: application/json" \
  -F "game=rosok-garage" \
  -F "bundle=@build/game.zip" \
  -F "rollout=20" \
  -F "changelog=$(git log -1 --pretty=%s)"

```

--------------------------------

### Install and Login to taploka-mcp

Source: https://taploka.hyuu.dev/docs/mcp-server

Commands to add the taploka MCP server to Claude and authenticate the local machine with the arcade.

```bash
claude mcp add taploka -- npx -y taploka-mcp@latest
npx -y taploka-mcp@latest login

```

--------------------------------

### GET /api/v1/harness/games/{game}

Source: https://taploka.hyuu.dev/docs/harness-api

Retrieves detailed metadata for a specific game.

```APIDOC
## GET /api/v1/harness/games/{game}

### Description
Retrieves detailed metadata for a specific game, including version history, rollout info, and leaderboard URL.

### Method
GET

### Endpoint
/api/v1/harness/games/{game}

### Parameters
#### Path Parameters
- **game** (string) - Required - The slug of the game
```

--------------------------------

### GET /api/v1/harness/games

Source: https://taploka.hyuu.dev/docs/harness-api

Lists all games in the catalog.

```APIDOC
## GET /api/v1/harness/games

### Description
Lists all games in the catalog including slug, title, status, version count, and play URL.

### Method
GET

### Endpoint
/api/v1/harness/games
```

--------------------------------

### ready()

Source: https://taploka.hyuu.dev/docs/game-sdk

Initializes the SDK and retrieves session information. Call this once at game start-up.

```APIDOC
## ready()

### Description
Initializes the SDK and returns game, version, player, and SDK metadata. This must be called once at start-up.

### Signature
`await taploka.ready()`

### Returns
- **game** (object) - Information about the current game.
- **version** (string) - The version of the game running.
- **player** (object) - Information about the current player.
- **sdk** (object) - SDK metadata.
```

--------------------------------

### Initialize SDK with ready()

Source: https://taploka.hyuu.dev/docs/game-sdk

Call ready() once at start-up to retrieve game, version, player, and SDK information.

```javascript
const { game, version, player, sdk } = await taploka.ready();
```

--------------------------------

### Push a Bundle

Source: https://taploka.hyuu.dev/docs/harness-api

Upload a ZIP file as a bundle to an existing game or create a new one.

```http
POST /api/v1/harness/bundles
Content-Type: multipart/form-data

```

```http
{
    "game": "rosok-garage",
    "game_created": true,
    "version": 1,
    "status": "released",
    "rollout": 100,
    "sdk_min": 1,
    "size_bytes": 69414,
    "files": 5,
    "play_url": "https://your-arcade.example.com/main/rosok-garage",
    "checks": [{ "label": "Struktur wajib", "detail": "index.html + game.json ditemukan", "ok": true }]
}
```

--------------------------------

### POST /api/v1/harness/bundles

Source: https://taploka.hyuu.dev/docs/harness-api

Uploads a game bundle to the catalog.

```APIDOC
## POST /api/v1/harness/bundles

### Description
Uploads a ZIP file bundle to the catalog.

### Method
POST

### Endpoint
/api/v1/harness/bundles

### Request Body (multipart/form-data)
- **bundle** (file) - Required - The ZIP file to upload
- **game** (string) - Required unless title is provided - Slug of an existing game
- **title** (string) - Optional - Name for a first push
- **rollout** (integer) - Optional - 0-100, default 100
- **changelog** (string) - Optional - Short note
- **draft** (integer) - Optional - Set to 1 to store without releasing

### Response
#### Success Response (200)
- **game** (string) - The game slug
- **game_created** (boolean) - Indicates if a new game was created
- **version** (integer) - The version number
- **status** (string) - The release status
- **play_url** (string) - The URL to play the game
```

--------------------------------

### push_game

Source: https://taploka.hyuu.dev/docs/mcp-server

Uploads a game bundle and releases it to the arcade. Supports zipping local folders, setting rollout percentages, and creating draft versions.

```APIDOC
## push_game

### Description
Uploads a game bundle and releases it. A folder is zipped locally, skipping dotfiles and node_modules.

### Parameters
- **zip** (string) - Required - Path to a ZIP or a folder.
- **title** (string) - Optional - Name of the game. Used for slug derivation on first push.
- **game** (string) - Optional - Slug of an existing game. Required for all pushes after the first.
- **rollout** (number) - Optional - Percentage of players served this version (0–100). Default 100.
- **changelog** (string) - Optional - Short note stored with the version.
- **draft** (boolean) - Optional - Store and validate without releasing. Default false.

### Response
Returns the version number, status, rollout, file count, play URL, and the full list of validation checks.
```

--------------------------------

### Connect machine with MCP

Source: https://taploka.hyuu.dev/docs/quickstart

Add the taploka MCP and log in to your arcade instance. This stores credentials in ~/.taploka/credentials.json.

```bash
claude mcp add taploka -- npx -y taploka-mcp@latest
npx -y taploka-mcp@latest login --url=https://your-arcade.example.com
```

--------------------------------

### Verify connection

Source: https://taploka.hyuu.dev/docs/quickstart

Check that the authentication was successful.

```bash
npx -y taploka-mcp@latest whoami
```

--------------------------------

### Configure Multiple Profiles

Source: https://taploka.hyuu.dev/docs/mcp-server

Commands to log in to a specific arcade profile and add it to the Claude MCP configuration.

```bash
npx -y taploka-mcp@latest login --profile=prod --url=https://your-arcade.example.com
claude mcp add taploka-prod -e TAPLOKA_PROFILE=prod -- npx -y taploka-mcp@latest

```

--------------------------------

### POST /api/v1/harness/games/{game}

Source: https://taploka.hyuu.dev/docs/harness-api

Updates metadata for an existing game.

```APIDOC
## POST /api/v1/harness/games/{game}

### Description
Updates game metadata fields such as title, description, or cover image.

### Method
POST

### Endpoint
/api/v1/harness/games/{game}

### Parameters
#### Path Parameters
- **game** (string) - Required - The slug of the game

### Request Body
- **title** (string) - Optional
- **tagline** (string) - Optional
- **description** (string) - Optional
- **orientation** (string) - Optional
- **max_score** (integer) - Optional
- **sort_order** (integer) - Optional
- **categories** (array) - Optional
- **features** (array) - Optional
- **cover_url** (string) - Optional
- **cover** (file) - Optional - Multipart file upload
```

--------------------------------

### POST /api/v1/harness/device

Source: https://taploka.hyuu.dev/docs/harness-api

Initiates the device link handshake to obtain a device code for authentication.

```APIDOC
## POST /api/v1/harness/device

### Description
Initiates the device link handshake to obtain a device code for authentication.

### Method
POST

### Endpoint
/api/v1/harness/device

### Request Body
- **name** (string) - Required - The name of the device (e.g., "build-box")

### Response
#### Success Response (200)
- **device_code** (string) - The code used for polling the token
- **user_code** (string) - The code to be approved in the admin console
- **verification_uri** (string) - The URL for manual verification
- **verification_uri_complete** (string) - The URL with the code pre-filled
- **interval** (integer) - Polling interval in seconds
- **expires_in** (integer) - Expiration time in seconds
```

--------------------------------

### exit()

Source: https://taploka.hyuu.dev/docs/game-sdk

Closes the game and returns the player to the catalog.

```APIDOC
## exit()

### Description
Requests the host to close the game and return the player to the catalog.
```

--------------------------------

### Manage cloud save with save() and load()

Source: https://taploka.hyuu.dev/docs/game-sdk

Persists game state to the cloud per player and per game. Objects are automatically serialized.

```javascript
await taploka.save({ level: 3, coins: 120 });
const state = await taploka.load();   // parsed object, or null on a fresh player
```

--------------------------------

### Push game as draft

Source: https://taploka.hyuu.dev/docs/quickstart

Upload a version as a draft to validate it without serving it to players.

```javascript
push_game { game: "rosok-garage", zip: "…", draft: true }
```

--------------------------------

### Push game response

Source: https://taploka.hyuu.dev/docs/quickstart

The output confirming the game creation and version release.

```text
rosok-garage v1 released · rollout 100% · sdk_min 1 · 5 files · game created
```

--------------------------------

### Check game status

Source: https://taploka.hyuu.dev/docs/quickstart

Retrieve the version ladder, rollout status, and play URL for a specific game.

```javascript
game_status { game: "rosok-garage" }
```

--------------------------------

### Required bundle file layout

Source: https://taploka.hyuu.dev/docs/bundles

The mandatory structure for the ZIP archive, requiring index.html and game.json at the root.

```text
index.html      entry point, at the root of the archive
game.json       manifest, at the root of the archive
assets/…        anything else, in any structure you like
```

--------------------------------

### save(payload) and load()

Source: https://taploka.hyuu.dev/docs/game-sdk

Manages cloud-based game state persistence.

```APIDOC
## save(payload)

### Description
Saves the game state to the cloud.

### Parameters
- **payload** (object) - The state object to store.

### Returns
- **revision** (number) - The revision number of the saved state.

## load()

### Description
Retrieves the saved game state.

### Returns
- **state** (object|null) - The parsed state object, or null if no save exists.
```

--------------------------------

### Retrieve leaderboard with leaderboard()

Source: https://taploka.hyuu.dev/docs/game-sdk

Fetches leaderboard entries and the current player's rank.

```javascript
const { entries, userRank } = await taploka.leaderboard(20);
```

--------------------------------

### game.json manifest structure

Source: https://taploka.hyuu.dev/docs/bundles

The required manifest file format for defining game metadata and settings.

```json
{
    "id": "rosok-garage",
    "sdk_version": 1,
    "orientation": "portrait",
    "settings": {}
}
```

--------------------------------

### Push new game

Source: https://taploka.hyuu.dev/docs/quickstart

Upload a game folder to create a new entry. The slug is derived from the title.

```javascript
push_game { title: "Rosok Garage", zip: "/path/to/rosok-garage" }
```

--------------------------------

### track(name, params?)

Source: https://taploka.hyuu.dev/docs/game-sdk

Logs gameplay events for analytics.

```APIDOC
## track(name, params?)

### Description
Logs a gameplay event for analytics purposes.

### Parameters
- **name** (string) - The name of the event.
- **params** (object, optional) - Additional event parameters.
```

--------------------------------

### Push game update

Source: https://taploka.hyuu.dev/docs/quickstart

Update an existing game by referencing its slug and providing a changelog.

```javascript
push_game { game: "rosok-garage", zip: "/path/to/rosok-garage", changelog: "fixed hitboxes" }
```

--------------------------------

### Exit game with exit()

Source: https://taploka.hyuu.dev/docs/game-sdk

Requests the host to close the game and return the player to the catalog.

```javascript
taploka.exit();
```

--------------------------------

### POST /api/v1/harness/device/token

Source: https://taploka.hyuu.dev/docs/harness-api

Polls for the authentication token after the device code has been approved.

```APIDOC
## POST /api/v1/harness/device/token

### Description
Polls for the authentication token after the device code has been approved.

### Method
POST

### Endpoint
/api/v1/harness/device/token

### Request Body
- **device_code** (string) - Required - The device code received from the initial request

### Response
#### Success Response (200)
- **token** (string) - The bearer token for API authentication

#### Pending Response (202)
- **status** (string) - Returns "pending" if not yet approved
```

--------------------------------

### Track events with track()

Source: https://taploka.hyuu.dev/docs/game-sdk

Fires a gameplay event for analytics purposes.

```javascript
taploka.track('level_end', { level: 4, outcome: 'win' });
```

--------------------------------

### game_status

Source: https://taploka.hyuu.dev/docs/mcp-server

Retrieves detailed information for a specific game.

```APIDOC
## game_status

### Description
Returns one game in detail: metadata, the version ladder with rollout and sizes, score totals, play and leaderboard URLs.
```

--------------------------------

### Request Device Code

Source: https://taploka.hyuu.dev/docs/harness-api

Initiate the device link flow by requesting a code for a specific device name.

```http
POST /api/v1/harness/device
Content-Type: application/json

{ "name": "build-box" }

```

```http
{
    "device_code": "…",
    "user_code": "RT2H-Z46S",
    "verification_uri": "https://your-arcade.example.com/admin/link",
    "verification_uri_complete": "https://your-arcade.example.com/admin/link?code=RT2H-Z46S",
    "interval": 2,
    "expires_in": 600
}
```

--------------------------------

### Read Catalog Games

Source: https://taploka.hyuu.dev/docs/harness-api

Retrieve a list of games or details for a specific game.

```http
GET /api/v1/harness/games
GET /api/v1/harness/games/{game}

```

--------------------------------

### leaderboard(limit?)

Source: https://taploka.hyuu.dev/docs/game-sdk

Retrieves the current leaderboard entries.

```APIDOC
## leaderboard(limit?)

### Description
Fetches the leaderboard entries.

### Parameters
- **limit** (number, optional) - The maximum number of entries to return.

### Returns
- **entries** (array) - List of leaderboard entries with display names and scores.
- **userRank** (number) - The current player's position.
```

--------------------------------

### submitScore(score, meta?)

Source: https://taploka.hyuu.dev/docs/game-sdk

Submits a player's score to the leaderboard.

```APIDOC
## submitScore(score, meta?)

### Description
Submits a score to the leaderboard. The score is floored to a non-negative integer.

### Parameters
- **score** (number) - The score to submit.
- **meta** (object, optional) - Additional metadata, such as level information.

### Returns
- **accepted** (boolean) - Whether the score was accepted or held for review.
- **rank** (number) - The player's rank.
- **best** (number) - The player's best score.
```

--------------------------------

### list_games

Source: https://taploka.hyuu.dev/docs/mcp-server

Retrieves a list of all games associated with the current profile.

```APIDOC
## list_games

### Description
Returns every game with its status, version count, live version, and play URL.
```

--------------------------------

### Authentication Header

Source: https://taploka.hyuu.dev/docs/harness-api

Requests must include a harness token as a bearer token in the Authorization header.

```http
Authorization: Bearer <token>
Accept: application/json

```

--------------------------------

### update_game

Source: https://taploka.hyuu.dev/docs/mcp-server

Updates the metadata and configuration for an existing game. Only provided fields are modified.

```APIDOC
## update_game

### Description
Change what players see. Only the fields you pass are touched.

### Parameters
- **game** (string) - Required - The slug of the game to update.
- **title** (string) - Optional
- **tagline** (string) - Optional
- **description** (string) - Optional
- **cover** (string) - Optional - Local image path (PNG, JPEG, or WebP, max 2 MB).
- **cover_url** (string) - Optional
- **categories** (array) - Optional - Lowercase slugs, max 5.
- **features** (array) - Optional - Options: 'offline', 'leaderboard', 'cloud_save'.
- **orientation** (string) - Optional
- **max_score** (number) - Optional
- **sort_order** (number) - Optional
```

--------------------------------

### Submit score with submitScore()

Source: https://taploka.hyuu.dev/docs/game-sdk

Submits a score to the leaderboard. The score is floored to a non-negative integer, and optional metadata can be provided.

```javascript
const { accepted, rank, best } = await taploka.submitScore(1200, { level: 4 });
```

--------------------------------

### Update Game Metadata

Source: https://taploka.hyuu.dev/docs/harness-api

Update specific metadata fields for a game.

```http
POST /api/v1/harness/games/{game}

```

--------------------------------

### Error Response Format

Source: https://taploka.hyuu.dev/docs/harness-api

Standard JSON structure for API error responses.

```json
{ "message": "…", "code": "BUNDLE_INVALID", "data": { "checks": [] } }

```

--------------------------------

### Poll for Device Token

Source: https://taploka.hyuu.dev/docs/harness-api

Poll the device token endpoint using the device code after the user has approved the request.

```http
POST /api/v1/harness/device/token
Content-Type: application/json

{ "device_code": "…" }

```
Tokens:
Raw