#Introduction

This page is the integration specification for publishers and developers who ship games on TapFun through cloud gaming. Your Windows exe runs on a Windows server in the cloud and is streamed to the player's browser. It is best suited to titles monetized by play time that do not download additional assets.

If your game runs in the browser, see the Web App specification instead.

#Getting to a test play

1. Submit a zip file containing an executable exe.
2. We send you a link to play it in the test environment. Check how it feels and plays.
3. To keep testing after the free play time runs out, purchase energy or a title pass. Choose "AmazonPay" as the payment method (Payments in the test environment).

If the test play shows no major issues, continue with the steps below.

#Setting up communication

• Email is the default channel.
• If needed, TapFun creates a Slack Connect channel shared by both companies.
• If you cannot join a Slack Connect channel, we will join your company's communication tool instead.

#Logging in to the Publisher Console

You can update your exe and change settings in the Publisher Console of the test environment (https://<TEST_HOST>/publisher). Your TapFun contact grants login access, so send us the email addresses of the people who will log in.

#Release planning

Once the remaining issues have a clear path to resolution, we agree on the release date and pricing.

#Reporting issues during development

When you hit a problem such as "input does not respond" or "unexpected behavior", report it in the communication channel with:

• The app name where the problem reproduces (if the test environment has several copies of the same game, include the app ID or other identifying information)
• The TapFun user account in the test environment where it happened (unless it only happens as a guest)
• Screenshots that show the situation
• A screen recording of the full reproduction steps, if screenshots are not enough
• The steps to reproduce

If the problem comes from intended behavior, both parties may discuss adding or changing a feature.

#Requirements for the exe

• Any game engine is fine, as long as it is an exe that runs on Windows. Whether it actually works is checked in the private test environment (a 13 GB title runs fine).
• There is no installation step. The zip is extracted and the exe is launched directly. Bundled runtime installers (Visual C++ Redistributable, OpenAL, etc.) are not run, so put the required DLLs in the same folder as the exe.
• Do not reference files by absolute path from the exe. Paths differ between your PC and the cloud. Use relative paths.
• The game must start without Steam or other store clients. If you use Steamworks, remove it from the build or make the game continue when initialization fails (without Steam, initialization tends to fail or hang at startup). No other SDK, DRM or launcher support is needed.
• If the game picks its language from the Steam setting, TapFun cannot detect it. Set the language through the OS locale, a bundled settings file, or the "exe launch parameters" in the Publisher Console (shared by the whole title).
• We need the exe itself for testing. Testing with a Steam key is not possible.
• Give the zip a name that identifies the title (e.g. MyGame_Demo.zip).

#Adjusting the exe

Before release, adjust the exe as follows.

• Save data must be stored under one of the supported paths. If it already is, tell TapFun the directory. If not, the exe needs to change. The Windows registry cannot be used.
• If the game starts in a window, make it start in full screen.
• If the in-game settings let players toggle full screen, we recommend disabling that option.
• If players can quit the game from inside it (terminating the exe process), we recommend disabling that.
• In-game external links (store pages, credit URLs, etc.) do not work, because they try to open in the cloud rather than in the player's browser. Use openUrl to open external URLs.
• Features that open other Windows apps or folders, such as "Open save folder", do not work. Hide them.
• Remove any on-screen debug display before submitting.

#From testing to release

1. Test in the test environment: after the Basic auth, log in with a TapFun account you create yourself (login is required to play). You can also launch a version from "このバージョンで起動" (launch this version) in the Publisher Console version list.
2. Final check in production: access to the production Publisher Console is granted separately. Before release, check the private app using Test play in production.
3. Publish: TapFun publishes the title. The publish time can be set between 10:00 and 17:00 JST.

• From receiving the exe to release takes about one month (including preparing the cloud environment and testing and adjusting the cloud version).
• The Publisher Console has no roles. Everyone who can log in can do the same things. To add people, send their email addresses to TapFun.

#Debugging

Add one of these parameters to the game page URL to see the client API traffic.

#Player support

• TapFun handles inquiries about the TapFun platform (login, payment, the game not starting, etc.). When needed, we share them with you along with the player ID.
• Inquiries about the game content are directed to your support contact. Prepare a contact point (such as a form) and let TapFun know.

#FAQ

Q. There is no sound until I click the game screen. A. This is expected behavior caused by browser restrictions.

Q. The gamepad does not respond. A. It responds after you click the game screen. It sometimes works without a click, but as a rule, click the game screen first.

Q. On iPhone, the sound stops after switching back from another app. A. This can happen in any title, though not every time. With the sound off, go back to the home screen once and return to the browser; the sound comes back.

#Environments

#Hostnames

The test environment hostname and its Basic auth user name and password are confidential and are not included in this document. Ask your TapFun contact for them. Replace <TEST_HOST> in code examples with the test environment hostname. Do not share them outside your company or anywhere public (public repositories, public channels, and so on).

#Payments in the test environment

To buy energy or a title pass in the test environment, use one of the following.

• AmazonPay: takes you to the "Multi-Payment Service test environment". Select "決済する" (Pay) to complete the payment.
• Test credit card: number 4111111111111111, any future expiry month/year, any 3-digit security code.

#Test play in production

To access an app before release, enable maintenance mode in the Publisher Console's basic settings and enter the tester's email address in "Maintenance exception email addresses".

For tests in production that involve purchases, TapFun registers a test-play account for each app. The account receives TapFun credit usable only in that app. Purchases by test-play accounts are cancelled immediately and offset against sales.

#Publisher Console

#Basic settings

#Details (introduction page)

The "詳細情報" (details) tab edits what is shown on the game's introduction page on TapFun.

Drag controls guide images and screenshots to reorder them. To delete one, click it to mark it for deletion, then press "追加アップロード & 順序を保存" (upload and save order) to apply the change.

#Sales settings

Sales settings are display-only. Contact TapFun to change anything other than DLC.

#DLC

• Manage the DLC sold on TapFun's web pages in the Publisher Console.
• When a title pass is on sale, DLC is sold both as a "title pass bundle" and as standalone DLC for owners of the standard edition.
• Describe DLC in YAML. You can register several (there is no limit, but contact us before registering more than one).
• If the player owns DLC, the exe is launched with --dlcs code,code,... (Launch parameters).

- name: Digital Deluxe Upgrade
  code: digital_deluxe_upgrade
  price: 3270
  bundlePrice: 2000
  archived: false
  description: |
    Upgrades the standard edition to the Digital Deluxe edition.
    - Collaboration outfits (6)
    - "Photo frame" camera feature (6 types)

#Steam

For titles with a Steam store page, a Steam store purchase widget is shown on the play screen at PC width.

#Updating the binary

• You can upload up to 5 versions, including the one in use. Versions other than the one in use can be deleted.
• After uploading, select "First Release" in the version list to release it (Sessions during a release).
• You can launch the game with any uploaded version.
• You cannot upload another version until the newly uploaded one has been released.
• The steps are the same for the test and production environments.
• The version set as "First Release" is the one players launch. To roll back, set an earlier version as "First Release".
• After uploading, processing takes a while before the version can be used. As a guide, 1-5 GB takes up to 30 minutes. Do not upload multiple versions at the same time.
• An upload can end in the "failed" state. If deleting and retrying does not help, contact TapFun.

#Sessions during a release

The "バイナリ" (binary) tab:

• zip structure: the zip must contain a folder named after "folder", with the "exe" inside it (<folder>/<exe>).
• When you cannot upload: if the screen shows "失敗したバージョンを削除してください" (delete the failed version), "不要なバージョンを削除してください" (delete unneeded versions; the limit of 5 is reached) or "First Release 待ちのバージョンがあります" (a version is waiting for First Release), follow that instruction.
• ApplicationVersions: list of uploaded versions. For each version you can use "First Release" (release), "Revert Version" (go back to an earlier version), "削除" (delete) and "このバージョンで起動" (launch this version).
• Tools → Save data download: enter a TapFun user ID to download that player's save data (do this a few minutes after the game exits).

#Launching the game

"アプリページ" (app page) at the top of the app screen launches the game with the options below (Debugging). Unreleased apps show "非公開状態" (private).

#Other tabs

#Cloud runtime

#How it works (important)

TapFun runs the game on a server and the player controls it remotely from the browser (remote desktop model). The cloud gaming platform is built on Tencent CAR.

• The exe runs on a Windows server in the cloud (Windows Server 2019 / 2022).
• The desktop graphics and audio output are captured and streamed to a canvas element in the browser (tapfun.co.jp). Start the game in full screen.
• Mouse and keyboard input inside the canvas is sent to the exe on the Windows server.
• There is no limit on game size.
• Maximum resolution is 1920x1080 (the default) and maximum refresh rate is 60 fps. Change the resolution with "Desktop width / height" in the Publisher Console.
• Video formats playable through Windows Media Foundation are H.264 / H.265. VP9 is not supported.
• Additional asset downloads are normally not possible (they would be stored as per-user data; contact us depending on size).
• Contact us if you want to use other Tencent CAR features or APIs.

#Server specs

#Network requirements

Requirements when your game servers communicate with the game runtime environment.

• Inbound: allow UDP 8000 and 60000-60100 from all sources.
• If you cannot allow all sources, in the test environment it works if you allow only these IPs: 124.156.222.35, 124.156.224.128, 43.130.251.233, 43.133.176.140, 43.133.180.230, 43.133.218.250, 43.153.145.189, 43.153.153.36, 43.153.155.47, 43.153.157.78, 43.163.247.41, 150.109.195.27
• Source IP: the source IP of outbound HTTP and other traffic from the servers running the exe is not disclosed.

#User data save and restore

User data is restored automatically at launch and saved automatically at exit.

• The save/restore directory is configurable per title, and only one directory is allowed. We recommend keeping the total size within 100 MB.
• Save data is kept per TapFun account and carries over when you update the build.
• Data is saved to cloud storage after the game exits. When downloading save data from the Publisher Console, wait a few minutes after the game exits.
• Supported paths (under one of these):
  • C:\Users\%UserName%\AppData\Local\<any directory>
  • C:\Users\%UserName%\AppData\LocalLow\<any directory>
  • C:\Users\%UserName%\AppData\Roaming\<any directory>
  • <root of the uploaded zip>\<any directory>
• Files placed directly in the exe's folder are not saved. Create a folder at least one level below the exe's folder and save there.
• Put nothing but save data in the save data directory. Every file in it is saved and restored as save data. If it contains DLLs, assets or other files, the old saved copies are restored instead of the latest files from your uploaded zip, which causes bugs.
• %UserName% is the Windows login user name. It is fairly stable but essentially random, so only rely on it within a single session.
• Tell TapFun the directory name you use. Data written to the registry is not restored. Unity's PlayerPrefs is stored in the registry on Windows, so switch to saving to files.
• There is no feature to reset save data. To check first-time-only behavior (tutorials, etc.), use another TapFun account.
• Saving does not work correctly until the save directory has been configured. Test save behavior after it is configured.

Examples of save directories:

#Supported input

Player input arrives at Windows in the cloud as follows.

• Titles with "Gamepad support" enabled in the Publisher Console can be played from smartphones and tablets (iOS / Android). Players use the on-screen virtual pad (sticks, D-pad, buttons and an Esc key button) or tap. For titles played by tapping only, enable "Gamepad support" and disable "Virtual pad default".
• Virtual pad input arrives as gamepad input, so no extra implementation is needed in the game (in Unreal Engine, the engine's gamepad settings work as-is).
• Keyboard input cannot be sent from smartphones and tablets. If a scene can only be advanced with a key (such as "Press A to start"), players on smartphones and tablets get stuck. Make it work with taps or a gamepad too.
• There is no virtual mouse cursor on touch devices. A touch arrives as a mouse click at that position. Additional fingers (multi-touch) may not be distinguished.
• Gamepad vibration is not supported.
• Gamepads and the virtual pad respond after the game screen has been clicked (tapped) once (FAQ).

#Gamepad

In most cases gamepads work as-is.

#Workaround

In your game, accept input from only one gamepad.

1. Make the first gamepad that sends input (a button or a stick) the "active" one, and ignore input from all other gamepads.
2. When the active gamepad disconnects, clear it and make the next gamepad that sends input the new active one.
3. In case a player switches controllers on a regular PC, switch the active gamepad to another one only when the active one has had no input for about one second.

The two controllers in the cloud receive the same input a few milliseconds apart, so the controls behave the same whichever becomes active. Because this does not depend on the controller type or name, it keeps working on a regular PC and after the platform is fixed and only one controller remains.

#Launch parameters

Only for apps that integrate with the TapFun API, the exe is launched with --tapfun-user-id and other parameters. They are not added by default. Contact your TapFun contact if you need them (we enable it in the admin console). Otherwise the exe receives only the "exe launch parameters" set in the Publisher Console.

C:\Apps\%UserName%\TapFunDebugConsoleApp.exe --type car --port 10100 --bearer-token 123_AAABBBCCC --api-host <TEST_HOST> --sig-key FFFGGGHHH --is-paid-timer 0 --is-sp 0 --tapfun-user-id PLYR01HE2R3JV6Y2NEGRMS4KZQB861DBG --dlcs delux_upgrade,special_upgrade --username=%E3%81%82%E3%81%84

#Client API

APIs for communication between your exe and TapFun in the player's browser. Data you send passes through the player's browser, so never include secrets.

#Transport

Requests are HTTP POSTs to the TapFun API. Responses arrive over UDP that the exe listens on. Sending requires --tapfun-user-id and --bearer-token (Launch parameters).

Sending

Receiving

#Sample Unity project

• GitHub: https://github.com/tapfuncojp/debug-console-app (send us your GitHub account name for access)

Sending sample (Unity / C#):

public IEnumerator SendCustomEventToCar(string userId, WWWForm formData)
{
    // config.apiHost = --api-host, config.bearerToken = --bearer-token
    string url = $"https://{config.apiHost}/api/v1/custom_event?userId={userId}";
    using (UnityWebRequest www = UnityWebRequest.Post(url, formData))
    {
        www.SetRequestHeader("Authorization", $"Bearer {config.bearerToken}");
        yield return www.SendWebRequest();
    }
}

Receiving sample (Unity / C#):

private UdpClient udpServer;
private IPEndPoint udpEndPoint;
private Thread serverThread;
private int udpServerPort = 10100; // --port
private bool isDataChannelReceiveLoopRunning = false;

public void CarHandleDataChannel()
{
    try
    {
        udpEndPoint = new IPEndPoint(IPAddress.Parse("127.0.0.1"), udpServerPort);
        udpServer = new UdpClient(udpEndPoint);
        isDataChannelReceiveLoopRunning = true;
        serverThread = new Thread(CarDataChannelReceiveLoop);
        serverThread.IsBackground = true;
        serverThread.Start();
    }
    catch (Exception e)
    {
        Debug.LogError($"Failed to start UDP server: {e.Message}");
    }
}

private void CarDataChannelReceiveLoop()
{
    while (isDataChannelReceiveLoopRunning)
    {
        try
        {
            byte[] receivedBytes = udpServer.Receive(ref udpEndPoint);
            string receivedMessage = Encoding.UTF8.GetString(receivedBytes); // query string
            byte[] responseBytes = Encoding.UTF8.GetBytes("OK");
            udpServer.Send(responseBytes, responseBytes.Length, udpEndPoint);
            lock (queueLock)
            {
                receivedMessagesQueue.Enqueue(receivedMessage);
            }
        }
        catch (Exception e)
        {
            Debug.LogError($"Unexpected error in receive loop: {e.Message}");
            Thread.Sleep(1000); // wait a little before continuing after an unexpected error
        }
    }
}

#openUrl

Opens a URL in a new tab.

Response: none

#inputTextSingleLine

Shows a single-line text input modal.

Response:

#inputTextMultiLine

Shows a multi-line text input modal.

Response: input longer than 128 characters is split into a sequence of 128-character chunks and delivered in several notifications.

#inputTextMultiLineChunkText

Sends the initial text for inputTextMultiLine in chunks ahead of time. After sending all chunks, send inputTextMultiLine with end; the chunks are joined and the modal opens. Use this to send long text in parts.

Response: none

#copyText

Shows a modal that lets the player copy text to the clipboard.

Response: none

#showText

Shows a text modal.

Response: none

#getPlayerEnvironment

Gets the player's environment.

Response:

#launchSuccessNotice

Notifies the platform that the game launched successfully. Sending it dismisses the "Starting streaming" dialog sooner.

For apps that wait for this notice, mouse input is blocked until the notice arrives or streaming has continued past a threshold. This avoids the process hanging on mouse input before it has finished starting. The timer does not run while input is blocked. We tell you in advance whether your app is one of them.

Response: none

#consoleLog

Outputs a log line. Add ?verbose=1 to the game page URL to see it in the browser's developer tools console, or ?debugLog=1 to see it in the on-screen log area (Debugging).

Response: none

#clientStatus

Notifies changes in client state (no request needed, sent automatically).

Every notification includes req=clientStatus. Example: req=clientStatus&result=lastTimeRemain&second=90

#Web API

HTTP APIs called from your servers or from the exe.

#Common specification

#Authentication

Authenticate with the HTTP header Authorization: Bearer <AppID>_<APIKey> (the Bearer token in the Publisher Console).

Authorization: Bearer 123_NWU0MjlkY2ViYTVkOTdiYjIwNThmZTkxMDMzYWM4Y2JmNGUyMTQ0Ng

On authentication failure the API returns HTTP 403 with:

{"error":"no authorization"}

#POST /api/v1/photos

Saves an image to TapFun photo storage. Players can view and download images saved from games on TapFun. Authentication: required.

Limits:

• Max images stored: 1,000 (the oldest are deleted automatically beyond that)
• Max size: 10 MB per image (no overall limit)
• Max width/height: 12,000 pixels
• Max image size: 100 megapixels (e.g. 10,000 × 10,000)
• No wait between calls and no call limit

curl -F "file=@sample.jpg;type=image/jpeg" \
  -H "Authorization: Bearer 1_8an4dAfsIyEEvBbaKxd55P2Wgf" \
  "https://<TEST_HOST>/api/v1/photos?userId=PLYR01JY39A09EE40YQZRHWTT9EM1VDBG"

// Success
{ "result": "success" }
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other (file missing, too large, invalid type, etc.)
{ "result": "failure", "message": "other problems." }

#GET /api/v1/leaderboard/entries

Gets leaderboard entries. Authentication: required.

// Success
{
  "result": "success",
  "entries": [
    {
      "position": 1,
      "userId": "PLYR01HE2R3JV6Y2NEGRMS4KZQB861DBG",
      "userName": "Player",               // UTF-8, no emoji, 1-12 characters
      "score": 12345,
      "note": "extra info",               // up to 8192 characters
      "createdAt": "2025-09-24T00:00:00.000Z",
      "updatedAt": "2025-09-24T00:00:00.000Z"
    }
  ]
}
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other
{ "result": "failure", "message": "other problems." }

#POST /api/v1/leaderboard/entries

Creates or updates a leaderboard entry. If the score is less than or equal to the existing score, it is not updated. A leaderboard is created automatically for each name. Authentication: required.

// Success
{ "result": "success" }
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other
{ "result": "failure", "message": "other problems." }

#POST /api/v1/leaderboard/entries/delete

Deletes a leaderboard entry. Returns success even if there is no entry. Authentication: required.

// Success
{ "result": "success" }
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other
{ "result": "failure", "message": "other problems." }

#Glossary

#Runtime environment

The cloud streaming server that runs and streams the exe.

#TapFun user ID

• A unique ID of up to 64 characters that identifies a user. Issued per app.
• Characters: 0-9, a-z, A-Z.
• Format: PLYR + ULID + a per-app suffix of 3-7 characters (e.g. DBG, XENO, MOCODVLP).

#App ID

An unsigned int ID that identifies an app.

#API key

A 26-character string issued per app. Characters: 0-9, A-Z.

#Publisher Console

The management console for publishers, used for app settings, the introduction page, sales and more. The test and production environments each have their own, and TapFun registers who can log in.

#Introduction page

The game's page on TapFun (https://tapfun.co.jp/p/<app>). The play screen is https://tapfun.co.jp/p/<app>/play. Edit its contents under Details in the Publisher Console.

#Guest

A player who is not logged in to TapFun.

#TapFun wallet

The balance a player charges on TapFun, used for purchases on TapFun.

#TapFun credit

Wallet balance given to test-play accounts in production, usable only in the target app (Test play in production).

#Session

One play from launching the game in the cloud until it exits. Save data is stored when a session ends and restored when the next session starts.

#Trial time

Free play time set per title ("お試し分数" in the Publisher Console). One session recovers 12 hours after use.

#Energy

A unit players buy to extend play time. The play time per energy is set per title, with separate values for players with and without the title pass (Sales settings).

#Title pass

A per-title right of use that players can buy. After purchase, the player can play for free for a set time. A version bundled with DLC can also be sold (DLC).

#Paid-timer / free-timer user

A player with at least one second of paid play time remaining (from energy or the title pass) is a paid-timer user; otherwise a free-timer user. You can tell from the launch parameter --is-paid-timer or isPaidTimer of getPlayerEnvironment.

#First Release

The Publisher Console operation that makes an uploaded version the one players launch (Sessions during a release).

#Virtual pad

A virtual gamepad shown on the play screen on smartphones and tablets. Its input arrives at the exe as gamepad input (Supported input).

#Changelog

↑ Back to top