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 competion type is to play with your friends and family or with your co-workers, depending on where your VPin is located. New offline competition 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 saving 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 send once the competition starts. Another one is send, once the competition is finished, including the announcement of the winner.

When new highscores are submitted, the initials of the player is mapped against the build-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 competition where different players compete with their own VPin against each other. To start a competition, make sure to follow the given steps:

  1. Ensure that you have a working Discord bot (on your own server). See also how to setup the VPin Studio Discord bot.
  2. 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 setup in no time).
  3. 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 setup the VPin Studio Discord bot for details about this. This way, all player bots will be available on the same server.
  4. Next, the admin of the server creates a new Discord competition and selects the table and duration of it.
  5. When the competition starts, the competition data is read 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 highcores?

The highscore reset is required so that all players start from zero - or to be more accurate - start with the table default scores. If a player achieves a highscore that is higher than the one of the other players but not higher than all existing 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 Discord Competitions Work

Discord competitions using 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 sum up 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 Studion. The player who wants to join must select a matching table (ROM and maybe also a matching file size). After submitting the joining process, the local history is resetted and new highscores achieved for this table will be send to the discord channel are pinned to the channel.

Every other VPin bot that is participating the competition will the pinned messages. This way, the current highscore can be calculated and is updated with every highscore submit ob 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 this, 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 section "Competitions" 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 selected "Highscore Reset", the highscore will be resetted, 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 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 the ones 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