Balloons minigame

Game settings

game_duration_seconds

Duration of the game in seconds.

balloons_per_second

Rate at which balloons are spawned in number of balloons per second.

balloon_odds

Odds of spawning a balloon of a certain type. It is an array of objects with the following fields:

• type: Type of the balloon; for now it's just a name.
• taps_to_pop: Number of taps required to pop the balloon.
• picker_weight: Weight of the balloon in the picker; sum of all weights should add up to 10.
• value_seconds: Value of the balloon in seconds.

Example odds

[
    {
        "type": "basic",
        "taps_to_pop": 1,
        "picker_weight": 6,
        "value_seconds": 0.5
    },
    {
        "type": "basic",
        "taps_to_pop": 3,
        "picker_weight": 2,
        "value_seconds": 2
    },
    {
        "type": "basic",
        "taps_to_pop": 5,
        "picker_weight": 1,
        "value_seconds": 3.5
    },
    {
        "type": "skull",
        "taps_to_pop": 1,
        "picker_weight": 1,
        "value_seconds": -3
    }
]

leniency_bonus_ms

Bonus time in milliseconds for leniency. The pixel leniency is calculated based on balloon speed and latency between server and client. Bonus is added to that latency.

*_speed

min_x_speed, max_x_speed, min_y_speed, max_y_speed are minimum and maximum speed of the balloon in the x and y directions. The value of those fields is a float number between 0 and 1 which describes percentage of the screen width or height what then comes to pixels per second.

*_boundary

min_left_boundary, max_left_boundary, min_right_boundary, max_right_boundary are minimum and maximum left and right boundaries, which define where balloon bounces. The value of those fields is a float number between 0 and 1 which describes percentage of the screen width or height what then comes to pixels. For min_right_boundary and max_right_boundary the value is relative to min_left_boundary. By default min_left_boundary is 0 and max_right_boundary is 1.

Message types

game_start

This message is sent by client to initiate gameplay. Client needs to inform server about device screen size.

Example

{
    "type": "game_start",
    "payload": {
        "screen_width": 1080,
        "screen_height": 1920
    },
    "timestamp": "2025-01-21T13:27:02.145322Z"
}

game_settings

In response to game_start message, server sends game_settings message. This message contains game settings including timestamp when game ends.

Example

{
    "type": "game_settings",
    "payload": {
        "spawn_rate": 1,
        "game_duration": 5,
        "ends_at": "2025-01-21T13:27:07.510223Z"
    },
    "timestamp": "2025-01-21T13:27:02.510284Z"
}

balloon_spawn

After returning game_settings message, server sends balloon_spawn messages at a rate of spawn_rate per second. Balloons have boundaries and speeds set based client's device screen size.

Example

{
    "type": "balloon_spawn",
    "payload": {
        "balloon_id": "9n2ked0mqp",
        "type": "basic",
        "value_seconds": 0.5,
        "taps_to_pop": 1,
        "start_x": 927,
        "start_y": 0,
        "speed_x": 412.7168330453118,
        "speed_y": 494.30748452236384,
        "boundary_x_min": 994,
        "boundary_x_max": 1059
    },
    "timestamp": "2025-01-21T13:27:03.512045Z"
}

balloon_tap

Client sends balloon_tap message when user clicks on a balloon.

Example

{
    "type": "balloon_tap",
    "payload": {
        "balloon_id": "9n2ked0mqp",
        "position_x": 1012,
        "position_y": 494
    },
    "timestamp": "2025-01-21T13:27:04.512045Z"
}

tap_validation

Server sends tap_validation message to validate if balloon was in exact position when user clicked on it. If the click is valid, taps are incremented. The message contains is_popped field to indicate if balloon was popped which happens when there are no taps remaining.

Example

{
    "type": "tap_validation",
    "payload": {
        "balloon_id": "9n2ked0mqp",
        "valid": true,
        "taps_remaining": 0,
        "is_popped": true,
        "score": 0.5
    },
    "timestamp": "2025-01-21T13:27:04.772313Z"
}

game_end

Server sends game_end message when game duration comes to an end. This message contains final score and number of balloons popped.

Example

{
    "type": "game_end",
    "payload": {
        "final_score_seconds": 3.5,
        "balloons_popped": 3
    },
    "timestamp": "2025-01-21T13:27:07.511329Z"
}

Balloon types

basic

Basic balloons are the most common type of balloons, which have positive values. They come in the following variants:

• Taps to pop 1 -> value 0.5 seconds
• Taps to pop 3 -> value 2 seconds
• Taps to pop 5 -> value 3.5 seconds

skull

Skull balloons are negative value balloons. They come in only one variant:

• Taps to pop 1 -> value -3 seconds

Gameplay flow

sequenceDiagram
    participant Server
    participant Client
    autonumber
    Client ->> Server: game_start
    Server -->> Client: game_settings

    par Gameplay
        loop Spawning balloons
            Server->>Client: balloon_spawn
        end
    and
        loop Popping balloons
            Client-->>Server: balloon_pop
            Server-->>Client: pop_validation
        end
    end

    Server->>Client: game_end