Architecture · Retrospective
Porting a web game into a Telegram mini-app

On 10 October Planet Invasion went live as a Telegram mini-app. Our team in the Philippines launched it at the Web3PH x PBW Future Proof Tech Summit, where Playermon was a community partner, and players reached it through the Playermon bot on Telegram. The game itself was not new. We had announced Planet Invasion in October 2023 as the second Playermon game, and its first version ran on the web at planet.playermon.com.
I oversaw the port as CEO. Most of the effort in a port like this does not go into the screen. A tap game inside a chat window is a small interface. The work is deciding what an account is on the new platform, how a player's existing progress gets there, and what happens to the old account afterwards.
Two kinds of identity
On the web, an account was something we issued. A player registered with an email address, and that address was how we could ask for proof that the person at the keyboard owned the account.
Inside Telegram, identity arrives with the app. When someone opens a mini-app, Telegram passes it the user's Telegram ID along with the rest of its launch data. Nobody types a password. That is a better experience for the player, and it moves the root of trust: the account now follows whoever controls the Telegram login.
A port therefore has to join two identity systems, and the join has to be proved from the side that holds the value. Our migration guide, published on 17 October, takes the player through it in this order:
- Log in to the web version and open the Migrate section, which lists the resources that will move.
- Enter the Telegram ID shown inside the mini-app and agree to the transfer.
- Enter the confirmation code sent to the email address registered on the web account.
The web login and the email code both prove control of the account that holds the resources. The Telegram ID needs less proof, because pushing your own resources to the wrong Telegram account harms only you. What the flow asks of the player is a deliberate pause: an explicit agreement, then a code from their own inbox, before anything moves.
One account at a time
After migrating, the web account is deactivated, and the player continues only in Telegram. That line in the guide is the one I would defend hardest. If both accounts stayed live, the same resources would exist in two places, and a player could spend them twice. A migration that copies a balance without retiring its source is not a migration. It is a duplication with a delay.
The same rule applies to anything of value in a game, on a chain or off it. There must be one place where a balance is authoritative, and moving it means closing it at the source in the same step that opens it at the destination.
What does not fit
The Telegram version is a different game. Our 2023 announcement described Planet Invasion as exploring planets and gathering equipment and resources. In Telegram it is a tap game: short sessions, daily check-ins and coins, made for someone who opens it between messages. The community picked a tap game in a poll in August, and this year's run of Telegram tap games had already shown that people will play inside a chat app.
So not every resource has a place in the new version, and the guide says so plainly. Resources that cannot move are converted to PYM and deposited in the mini-app, to be withdrawn once the withdrawal function is complete. I would rather tell players that in writing before they migrate than let them discover an empty slot where an item used to be.
Sessions and wallets
A mini-app runs inside Telegram's own browser window, and the session belongs to Telegram. Two consequences follow for the server.
First, it should never trust a Telegram ID just because the page sends one. Telegram signs the launch data it hands to a mini-app, and the server can check that signature against the bot's token. An ID that arrives without that check is only a claim, and an account system built on claims can be walked into by anyone who can edit a request.
Second, the wallet stops being the front door. The migration steps involve no wallet at all. A player's PYM sits in the mini-app as a balance, and moving it anywhere else waits for the withdrawal function. That is the same order we chose on the web in 2023, when new players verified an email address and received starter Playermons before they ever held a key.
What I take from it
Porting a game is mostly an accounting exercise. Decide which account is the real one. Prove the link from the side that holds the value. Retire the source when the value moves. Tell players in writing what will not come across, and what it becomes instead. The screen was the easy part.