Competitions - syd711/vpin-studio GitHub Wiki
While playing pinball is fun, playing with/against other people is even more fun. That's why the VPin Studio supports two different competition modes to get more fun out of your VPin.
Offline Competitions
Offline competitions are created and played on solely one VPin. The intention of this competition type is to play with your friends and family or with your co-workers, depending on where your VPin is located. New offline competitions can be created by clicking on the Add button on the Offline Competitions tab.
Create New Offline Competition
Within the dialog, the start and end date, table, the optional Discord channel and the table badge can be set.
After the competition has been saved, it is added to the list of competitions and shows the current state.
Offline Competition Overview
If a Discord channel has been selected, a notification is sent once the competition starts. Another one is sent once the competition is finished, including the announcement of the winner.
When new highscores are submitted, the initials of the player are mapped against the built-in players and the Discord players of the server which has been selected for notifications.
Note that only tables are supported for selection which have a recorded highscore. So either the nvram extraction with pinemhi must have been executed successfully at least once, or the table must have an EM or VPReg.stg entry.
Discord Competitions
Discord competitions are actual online competitions where different players compete with their own VPin against each other. To start a competition, make sure to follow the given steps:
- Ensure that you have a working Discord bot (on your own server). See also how to set up the VPin Studio Discord bot.
- Decide on which Discord server the competition should take place. (Most likely every player has their own Discord server for their VPin, so everyone has to agree on one server to play on or create a separate one. Thanks to Discord, a new one is set up in no time.)
- Create a new Discord Bot URL on the Discord developer portal and send this link to the admin of the server you want to compete on. Again, read how to set up the VPin Studio Discord bot for details about this. This way, all player bots will be available on the same server.
- Make sure that your bot has the initials of your player(s). See How to link players and bots.
- Next, the admin of the server creates a new Discord competition and selects the table and duration of it.
- When the competition starts, the competition data is written into the topic of the selected Discord channel. Other players can only join after the competition has been started! The other players can join the competition by pressing the Join button on the Discord Competitions tab.
Create Discord Competition Dialog
Join Discord Competition Dialog
But why do I have to reset my highscores?
The highscore reset is required so that all players start from zero — or to be more accurate — start with the table's default scores. If a player achieves a highscore that is higher than the one of the other players but not higher than all existing ones on their VPin, no highscore change can be detected by the VPin Server. As a result, no score update is submitted to Discord and this new highscore would simply be ignored.
Read more about how to reset and restore highscores.
How to Link Players and Bots
Bots work as a proxy for your cabinet on a Discord channel. When a new highscore is created, the initials of your bot are checked and if these match, the new highscore is published on the configured Discord channel. To make this matching work, your bot must have the name pattern <NAME> | [<INITIALS>].
For example: Your bot has the name Matthias | [MFA]. When you create a new highscore on your cabinet with a player that has the initials MFA, the Studio server will detect that you have a bot with these initials and emit the highscore.
You can change the nickname of your bot to this format by right-clicking on it in Discord and select "Change Nickname".
An example of this can be seen in the screenshot below.
Here you see that the bot actually represents 2 of your players: one with the initials MFA and another one with the initials MFB. The bot can represent multiple players by adding the player initials in a comma-separated value format (without whitespaces!).
The player doesn't need to have a Discord account or be a member of the server for this. Your bot represents your whole family this way and posts scores for all players that have been created in the VPin Studio.
How Discord Competitions Work
Discord competitions use pinned messages to save competition data. That's why only one active competition per channel is allowed. When a Discord competition starts, the competition data is written as a base64 message with an additional image to summarize the information of the competition. The data message contains:
- competition name
- table name
- table ROM
- table size
- join mode
- start date
- end date
When other players want to join this competition, this data is read from the pinned message and offered in the Join dialog of the VPin Studio. The player who wants to join must select a matching table (ROM and optionally also a matching file size). After submitting the join request, the local history is reset and new highscores achieved for this table will be sent to the Discord channel and pinned to the channel.
Every other VPin bot participating in the competition will monitor the pinned messages. This way, the current highscore can be calculated and is updated with every highscore submission by a player.
Discord Competition: Highscores and Players
If the competition finishes, the winner will be announced in a separate notification and the topic data will be deleted automatically.
Note that all bots/VPins have their own database entry for the active competition, but only the owner of the competition is able to finish it. Therefore, the owner of the competition must make sure to come online with their VPin so that the bot can finish the competition and announce the winner.
Competition Badges
When creating a competition, an additional badge icon can be attached to the wheel icon of a table. If the table's wheel icon is already augmented at the time of the selection (because it is used in another parallel competition), the badge selection is ignored when the competition starts. The badge is automatically removed when the competition is finished.
Table Subscriptions
"Table Subscriptions" combine the best of both worlds: offline competitions and Discord competitions. Table subscriptions allow you to create a separate Discord channel for a table, depending on the ROM name of it. New highscores will be posted there so you can always check the current highscores of all your tables via Discord. Also, other players can subscribe to the channel. By doing so, their highscores will compete with yours.
Creating new subscriptions
Subscriptions can be created via two different methods: manually or automatically when a new highscore is created. To create a new subscription channel for a table, go to the "Table Subscriptions" tab under the "Competitions" section and click Add. You only have to select the server, Discord server category and table in order to create a new subscription.
Note that when you select "Highscore Reset", the highscore will be reset, but a backup will be created from the existing data.
If you have "Dynamic Subscriptions" enabled in the "Bot Settings" section, a new channel will be created on the fly when a new highscore is created for a table.
Subscribing to other tables
If your bot is on another Discord server (maybe you have created a shared one with friends), you can subscribe to a table's channel.
After selecting the channel, you only have to select the table on your cabinet that matches the one of the channel. After joining the channel, your new highscores for that table will be submitted to the channel and compared to those of your friends. An update will be posted for every new highscore submission.
More details about this can be found here: https://www.youtube.com/@vpin-studio/videos