big shot

2026-10-13 20:12:10 +00:00 · 2026-09-01 11:59:00 +02:00
10 changed files with 509 additions and 33 deletions
@@ -17,6 +17,7 @@ class PaperBallThrown implements ShouldBroadcastNow
        public readonly string $roomId,
        public readonly int $fromPlayerId,
        public readonly int $targetPlayerId,
+        public readonly int $chargeLevel,
    ) {}

    public function broadcastOn(): Channel
@@ -30,7 +31,7 @@ class PaperBallThrown implements ShouldBroadcastNow
    }

    /**
-     * @return array{id: string, from_player_id: int, target_player_id: int}
+     * @return array{id: string, from_player_id: int, target_player_id: int, charge_level: int}
     */
    public function broadcastWith(): array
    {
@@ -38,6 +39,7 @@ class PaperBallThrown implements ShouldBroadcastNow
            'id' => $this->id,
            'from_player_id' => $this->fromPlayerId,
            'target_player_id' => $this->targetPlayerId,
+            'charge_level' => $this->chargeLevel,
        ];
    }
 }
@@ -27,6 +27,7 @@ class RoomEmoteController extends Controller
            $room,
            $player,
            (int) $request->validated('target_player_id'),
+            (int) ($request->validated('charge_percentage') ?? 0),
        );

        return response()->noContent();
@@ -19,6 +19,7 @@ class ThrowPaperBallRequest extends FormRequest
    {
        return [
            'target_player_id' => ['required', 'integer'],
+            'charge_percentage' => ['sometimes', 'integer', 'between:0,300'],
        ];
    }
 }
@@ -11,8 +11,12 @@ use Illuminate\Validation\ValidationException;

 class RoomEmoteService
 {
-    public function throwPaperBall(Room $room, Player $player, int $targetPlayerId): void
-    {
+    public function throwPaperBall(
+        Room $room,
+        Player $player,
+        int $targetPlayerId,
+        int $chargePercentage,
+    ): void {
        if ($targetPlayerId === $player->id) {
            throw ValidationException::withMessages([
                'target_player_id' => 'Du kannst dich nicht selbst abwerfen.',
@@ -39,11 +43,19 @@ class RoomEmoteService

        RateLimiter::hit($rateLimitKey, 10);

+        $chargeLevel = match (true) {
+            $chargePercentage >= 300 => 3,
+            $chargePercentage >= 200 => 2,
+            $chargePercentage >= 100 => 1,
+            default => 0,
+        };
+
        PaperBallThrown::dispatch(
            Str::uuid()->toString(),
            $room->id,
            $player->id,
            $targetPlayerId,
+            $chargeLevel,
        );
    }
 }
@@ -1,14 +1,181 @@
 <script setup lang="ts">
 import { CircleUserRound, Crown } from '@lucide/vue';
+import { computed, onBeforeUnmount, ref } from 'vue';
+import type { CSSProperties } from 'vue';

 import type { RoomSeatProps } from '@/types/room';

 const props = defineProps<RoomSeatProps>();

 const emit = defineEmits<{
-    throwPaperBall: [playerId: number];
+    throwPaperBall: [playerId: number, chargePercentage: number];
 }>();

+const MAX_CHARGE_PERCENTAGE = 300;
+const CHARGE_DURATION = 3_000;
+const chargePercentage = ref(0);
+const chargeStartedAt = ref<number | null>(null);
+let chargeAnimationFrame: number | null = null;
+let ignoreClickTimer: number | null = null;
+let ignoreNextClick = false;
+
+const isCharging = computed(() => chargeStartedAt.value !== null);
+const seatStyle = computed<CSSProperties>(() => ({
+    ...props.player.seatStyle,
+    '--paper-ball-knockback-x': `${props.paperBallKnockback.x}px`,
+    '--paper-ball-knockback-y': `${props.paperBallKnockback.y}px`,
+}));
+
+function updateCharge(timestamp: number): void {
+    if (chargeStartedAt.value === null) {
+        return;
+    }
+
+    chargePercentage.value = Math.min(
+        MAX_CHARGE_PERCENTAGE,
+        ((timestamp - chargeStartedAt.value) / CHARGE_DURATION) *
+            MAX_CHARGE_PERCENTAGE,
+    );
+
+    if (chargePercentage.value < MAX_CHARGE_PERCENTAGE) {
+        chargeAnimationFrame = window.requestAnimationFrame(updateCharge);
+    } else {
+        chargeAnimationFrame = null;
+    }
+}
+
+function startCharging(): void {
+    if (props.throwDisabled || chargeStartedAt.value !== null) {
+        return;
+    }
+
+    chargePercentage.value = 0;
+    chargeStartedAt.value = performance.now();
+    chargeAnimationFrame = window.requestAnimationFrame(updateCharge);
+}
+
+function stopChargeAnimation(): void {
+    if (chargeAnimationFrame !== null) {
+        window.cancelAnimationFrame(chargeAnimationFrame);
+        chargeAnimationFrame = null;
+    }
+}
+
+function resetCharge(): void {
+    stopChargeAnimation();
+    chargeStartedAt.value = null;
+    chargePercentage.value = 0;
+}
+
+function finishCharging(): void {
+    if (chargeStartedAt.value === null) {
+        return;
+    }
+
+    updateCharge(performance.now());
+
+    const releasedChargePercentage = Math.min(
+        MAX_CHARGE_PERCENTAGE,
+        Math.floor(chargePercentage.value),
+    );
+
+    resetCharge();
+    emit('throwPaperBall', props.player.id, releasedChargePercentage);
+
+    ignoreNextClick = true;
+
+    if (ignoreClickTimer !== null) {
+        window.clearTimeout(ignoreClickTimer);
+    }
+
+    ignoreClickTimer = window.setTimeout(() => {
+        ignoreNextClick = false;
+        ignoreClickTimer = null;
+    });
+}
+
+function startPointerCharge(event: PointerEvent): void {
+    if (event.button !== 0) {
+        return;
+    }
+
+    (event.currentTarget as HTMLButtonElement).setPointerCapture(
+        event.pointerId,
+    );
+    startCharging();
+}
+
+function finishPointerCharge(event: PointerEvent): void {
+    const button = event.currentTarget as HTMLButtonElement;
+
+    if (button.hasPointerCapture(event.pointerId)) {
+        button.releasePointerCapture(event.pointerId);
+    }
+
+    finishCharging();
+}
+
+function cancelPointerCharge(): void {
+    resetCharge();
+}
+
+function handleKeyDown(event: KeyboardEvent): void {
+    if (!['Enter', ' '].includes(event.key)) {
+        return;
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+
+    if (!event.repeat) {
+        startCharging();
+    }
+}
+
+function handleKeyUp(event: KeyboardEvent): void {
+    if (!['Enter', ' '].includes(event.key)) {
+        return;
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+    finishCharging();
+}
+
+function handleClick(): void {
+    if (ignoreNextClick) {
+        ignoreNextClick = false;
+
+        return;
+    }
+
+    emit('throwPaperBall', props.player.id, 0);
+}
+
+function chargeSegmentProgress(segment: number): number {
+    return Math.min(100, Math.max(0, chargePercentage.value - segment * 100));
+}
+
+function chargeColor(): string {
+    if (chargePercentage.value > 200) {
+        return '#ef4444';
+    }
+
+    if (chargePercentage.value > 100) {
+        return '#f97316';
+    }
+
+    return '#22c55e';
+}
+
+onBeforeUnmount(() => {
+    stopChargeAnimation();
+
+    if (ignoreClickTimer !== null) {
+        window.clearTimeout(ignoreClickTimer);
+    }
+});
+
 function cardLabel(value: string | null): string {
    if (value === null) {
        return '–';
@@ -30,7 +197,7 @@ function playerVote(): string | null {
    <article
        class="player-seat"
        :class="{ 'is-paper-ball-hit': isPaperBallHit }"
-        :style="player.seatStyle"
+        :style="seatStyle"
        :data-player-id="player.id"
    >
        <div
@@ -98,12 +265,52 @@ function playerVote(): string | null {
            v-if="!isCurrentPlayer()"
            type="button"
            class="throw-paper-ball"
+            :class="{ 'is-charging': isCharging }"
            :disabled="throwDisabled"
-            :aria-label="`Papierknäuel auf ${player.name} werfen`"
-            :title="`Papierknäuel auf ${player.name} werfen`"
-            @click.stop="emit('throwPaperBall', player.id)"
+            :aria-label="`Papierknäuel auf ${player.name} werfen – gedrückt halten zum Aufladen${isCharging ? `, ${Math.floor(chargePercentage)} Prozent geladen` : ''}`"
+            :aria-pressed="isCharging"
+            :title="`Papierknäuel auf ${player.name} werfen – gedrückt halten zum Aufladen`"
+            @pointerdown.stop.prevent="startPointerCharge"
+            @pointerup.stop.prevent="finishPointerCharge"
+            @pointercancel="cancelPointerCharge"
+            @keydown="handleKeyDown"
+            @keyup="handleKeyUp"
+            @blur="cancelPointerCharge"
+            @click.stop.prevent="handleClick"
        >
-            <span class="paper-ball-mini" aria-hidden="true"></span>
+            <svg
+                v-if="isCharging"
+                class="charge-rings"
+                viewBox="0 0 48 48"
+                aria-hidden="true"
+            >
+                <g
+                    v-for="segment in 3"
+                    v-show="chargePercentage > (segment - 1) * 100"
+                    :key="segment"
+                >
+                    <circle
+                        class="charge-ring-track"
+                        cx="24"
+                        cy="24"
+                        :r="8 + segment * 4"
+                    />
+                    <circle
+                        class="charge-ring"
+                        cx="24"
+                        cy="24"
+                        :r="8 + segment * 4"
+                        pathLength="100"
+                        :stroke="chargeColor()"
+                        :stroke-dashoffset="
+                            100 - chargeSegmentProgress(segment - 1)
+                        "
+                    />
+                </g>
+            </svg>
+            <span class="throw-paper-ball-surface" aria-hidden="true">
+                <span class="paper-ball-mini"></span>
+            </span>
        </button>
    </article>
 </template>
@@ -113,7 +320,11 @@ function playerVote(): string | null {
    position: absolute;
    z-index: 2;
    width: 8rem;
-    transform: translate(-50%, -50%);
+    transform: translate(-50%, -50%)
+        translate(
+            var(--paper-ball-knockback-x, 0),
+            var(--paper-ball-knockback-y, 0)
+        );
    text-align: center;
 }

@@ -127,23 +338,22 @@ function playerVote(): string | null {

 .throw-paper-ball {
    position: absolute;
-    top: 0.65rem;
-    right: 0.35rem;
+    top: 0.15rem;
+    right: -0.15rem;
    z-index: 8;
    display: grid;
-    width: 2rem;
-    height: 2rem;
+    width: 3rem;
+    height: 3rem;
    place-items: center;
-    border: 1px solid #64748b;
-    border-radius: 0.5rem;
-    background: #334155;
+    border: 0;
+    background: transparent;
    opacity: 0;
    transform: translateY(0.25rem) rotate(-8deg);
    pointer-events: none;
+    touch-action: none;
    transition:
        opacity 140ms ease,
-        transform 140ms ease,
-        background-color 140ms ease;
+        transform 140ms ease;
 }

 .player-seat:hover .throw-paper-ball,
@@ -153,9 +363,14 @@ function playerVote(): string | null {
    pointer-events: auto;
 }

+.throw-paper-ball:hover:not(:disabled) .throw-paper-ball-surface,
+.throw-paper-ball:focus-visible .throw-paper-ball-surface,
+.throw-paper-ball.is-charging .throw-paper-ball-surface {
+    background: #475569;
+}
+
 .throw-paper-ball:hover:not(:disabled),
 .throw-paper-ball:focus-visible {
-    background: #475569;
    transform: translateY(-0.1rem) rotate(4deg);
 }

@@ -170,6 +385,46 @@ function playerVote(): string | null {
    pointer-events: none;
 }

+.throw-paper-ball-surface {
+    position: relative;
+    z-index: 1;
+    display: grid;
+    width: 2rem;
+    height: 2rem;
+    place-items: center;
+    border: 1px solid #64748b;
+    border-radius: 0.5rem;
+    background: #334155;
+    transition: background-color 140ms ease;
+}
+
+.charge-rings {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    overflow: visible;
+    filter: drop-shadow(0 0 0.2rem rgb(15 23 42 / 75%));
+}
+
+.charge-ring-track,
+.charge-ring {
+    fill: none;
+    stroke-width: 2.25;
+}
+
+.charge-ring-track {
+    stroke: rgb(148 163 184 / 32%);
+}
+
+.charge-ring {
+    transform: rotate(-90deg);
+    transform-origin: 24px 24px;
+    stroke-linecap: round;
+    stroke-dasharray: 100;
+    transition: stroke 100ms linear;
+}
+
 .paper-ball-mini {
    display: block;
    width: 0.95rem;
@@ -17,12 +17,17 @@ const hasCompactHeight = useMediaQuery(
 );

 const gameBoard = ref<HTMLElement | null>(null);
-const { activePaperBalls, hitPlayerIds, throwingAtPlayerId, throwPaperBall } =
-    usePaperBallToss({
-        roomId: () => props.room.id,
-        currentPlayerId: () => props.currentPlayer.id,
-        board: gameBoard,
-    });
+const {
+    activePaperBalls,
+    hitPlayerIds,
+    paperBallKnockbacks,
+    throwingAtPlayerId,
+    throwPaperBall,
+} = usePaperBallToss({
+    roomId: () => props.room.id,
+    currentPlayerId: () => props.currentPlayer.id,
+    board: gameBoard,
+});

 const positionedPlayers = computed<PositionedRoomPlayer[]>(() => {
    const currentPlayerIndex = props.room.players.findIndex(
@@ -99,6 +104,7 @@ const voteCount = computed(
                v-for="paperBall in activePaperBalls"
                :key="paperBall.id"
                class="paper-ball-flight"
+                :class="`paper-ball-level-${paperBall.chargeLevel}`"
                :style="paperBall.style"
                aria-hidden="true"
            >
@@ -115,6 +121,9 @@ const voteCount = computed(
                :revealed="room.revealed"
                :presenter-mode="presenterMode"
                :is-paper-ball-hit="hitPlayerIds.includes(player.id)"
+                :paper-ball-knockback="
+                    paperBallKnockbacks[player.id] ?? { x: 0, y: 0 }
+                "
                :throw-disabled="throwingAtPlayerId !== null"
                @throw-paper-ball="throwPaperBall"
            />
@@ -189,6 +198,21 @@ const voteCount = computed(
    animation: paper-ball-flight 780ms linear forwards;
 }

+.paper-ball-flight.paper-ball-level-1 {
+    width: 2.05rem;
+    height: 2.05rem;
+}
+
+.paper-ball-flight.paper-ball-level-2 {
+    width: 2.5rem;
+    height: 2.5rem;
+}
+
+.paper-ball-flight.paper-ball-level-3 {
+    width: 3rem;
+    height: 3rem;
+}
+
 .paper-ball {
    display: block;
    width: 100%;
@@ -4,7 +4,9 @@ import { toast } from 'vue-sonner';
 import { useRoomEmotes } from '@/composables/useRoomEmotes';
 import { store as throwPaperBallRoute } from '@/routes/room/emote/paper-ball';
 import type {
+    PaperBallChargeLevel,
    PaperBallFlight,
+    PaperBallKnockback,
    PaperBallThrowError,
    PaperBallThrownPayload,
    PaperBallTossOptions,
@@ -13,6 +15,14 @@ import type {
 const PAPER_BALL_FLIGHT_DURATION = 780;
 const SEEN_EVENT_RETENTION = 5_000;
 const THROW_BUTTON_COOLDOWN = 550;
+const MAX_KNOCKBACK_DISTANCE = 72;
+const KNOCKBACK_RETURN_SPEED = 58;
+const KNOCKBACK_FORCE: Record<PaperBallChargeLevel, number> = {
+    0: 0,
+    1: 18,
+    2: 32,
+    3: 48,
+};

 export function usePaperBallToss({
    roomId,
@@ -21,9 +31,12 @@ export function usePaperBallToss({
 }: PaperBallTossOptions) {
    const activePaperBalls = ref<PaperBallFlight[]>([]);
    const hitPlayerIds = ref<number[]>([]);
+    const paperBallKnockbacks = ref<Record<number, PaperBallKnockback>>({});
    const throwingAtPlayerId = ref<number | null>(null);
    const seenPaperBallIds = new Set<string>();
    const timers = new Set<number>();
+    let knockbackAnimationFrame: number | null = null;
+    let previousKnockbackFrameTime: number | null = null;

    function schedule(callback: () => void, delay: number): void {
        const timer = window.setTimeout(() => {
@@ -34,7 +47,87 @@ export function usePaperBallToss({
        timers.add(timer);
    }

-    async function throwPaperBall(targetPlayerId: number): Promise<void> {
+    function animateKnockbacks(timestamp: number): void {
+        const elapsed = Math.min(
+            timestamp - (previousKnockbackFrameTime ?? timestamp),
+            32,
+        );
+        const returnDistance = (KNOCKBACK_RETURN_SPEED * elapsed) / 1_000;
+        const nextKnockbacks: Record<number, PaperBallKnockback> = {};
+
+        Object.entries(paperBallKnockbacks.value).forEach(
+            ([playerId, knockback]) => {
+                const distance = Math.hypot(knockback.x, knockback.y);
+                const nextDistance = Math.max(0, distance - returnDistance);
+
+                if (nextDistance > 0.1) {
+                    const scale = nextDistance / distance;
+
+                    nextKnockbacks[Number(playerId)] = {
+                        x: knockback.x * scale,
+                        y: knockback.y * scale,
+                    };
+                }
+            },
+        );
+
+        paperBallKnockbacks.value = nextKnockbacks;
+        previousKnockbackFrameTime = timestamp;
+
+        if (Object.keys(nextKnockbacks).length > 0) {
+            knockbackAnimationFrame =
+                window.requestAnimationFrame(animateKnockbacks);
+
+            return;
+        }
+
+        knockbackAnimationFrame = null;
+        previousKnockbackFrameTime = null;
+    }
+
+    function applyKnockback(
+        playerId: number,
+        directionX: number,
+        directionY: number,
+        chargeLevel: PaperBallChargeLevel,
+    ): void {
+        const force = KNOCKBACK_FORCE[chargeLevel];
+
+        if (force === 0) {
+            return;
+        }
+
+        const currentKnockback = paperBallKnockbacks.value[playerId] ?? {
+            x: 0,
+            y: 0,
+        };
+        let nextX = currentKnockback.x + directionX * force;
+        let nextY = currentKnockback.y + directionY * force;
+        const nextDistance = Math.hypot(nextX, nextY);
+
+        if (nextDistance > MAX_KNOCKBACK_DISTANCE) {
+            const scale = MAX_KNOCKBACK_DISTANCE / nextDistance;
+
+            nextX *= scale;
+            nextY *= scale;
+        }
+
+        paperBallKnockbacks.value = {
+            ...paperBallKnockbacks.value,
+            [playerId]: { x: nextX, y: nextY },
+        };
+
+        if (knockbackAnimationFrame === null) {
+            previousKnockbackFrameTime = null;
+            knockbackAnimationFrame =
+                window.requestAnimationFrame(animateKnockbacks);
+        }
+    }
+
+    async function throwPaperBall(
+        targetPlayerId: number,
+        chargePercentage = 0,
+    ): Promise<void> {
        if (
            targetPlayerId === currentPlayerId() ||
            throwingAtPlayerId.value !== null
@@ -66,6 +159,7 @@ export function usePaperBallToss({
                },
                body: JSON.stringify({
                    target_player_id: targetPlayerId,
+                    charge_percentage: chargePercentage,
                }),
            });

@@ -106,6 +200,9 @@ export function usePaperBallToss({
            typeof payload.id !== 'string' ||
            !Number.isInteger(payload.from_player_id) ||
            !Number.isInteger(payload.target_player_id) ||
+            !Number.isInteger(payload.charge_level) ||
+            payload.charge_level < 0 ||
+            payload.charge_level > 3 ||
            seenPaperBallIds.has(payload.id)
        ) {
            return;
@@ -142,9 +239,12 @@ export function usePaperBallToss({
            targetRect.top + targetRect.height / 2 - boardRect.top - startY;
        const distance = Math.hypot(travelX, travelY);
        const arcHeight = Math.min(130, Math.max(55, distance * 0.22));
+        const knockbackDirectionX = distance === 0 ? 1 : travelX / distance;
+        const knockbackDirectionY = distance === 0 ? 0 : travelY / distance;

        activePaperBalls.value.push({
            id: payload.id,
+            chargeLevel: payload.charge_level,
            style: {
                left: `${startX}px`,
                top: `${startY}px`,
@@ -163,6 +263,13 @@ export function usePaperBallToss({
            if (!hitPlayerIds.value.includes(payload.target_player_id)) {
                hitPlayerIds.value.push(payload.target_player_id);
            }
+
+            applyKnockback(
+                payload.target_player_id,
+                knockbackDirectionX,
+                knockbackDirectionY,
+                payload.charge_level,
+            );
        }, PAPER_BALL_FLIGHT_DURATION - 80);

        schedule(() => {
@@ -183,11 +290,16 @@ export function usePaperBallToss({
    onScopeDispose(() => {
        timers.forEach((timer) => window.clearTimeout(timer));
        timers.clear();
+
+        if (knockbackAnimationFrame !== null) {
+            window.cancelAnimationFrame(knockbackAnimationFrame);
+        }
    });

    return {
        activePaperBalls,
        hitPlayerIds,
+        paperBallKnockbacks,
        throwingAtPlayerId,
        throwPaperBall,
    };
@@ -1,9 +1,12 @@
 import type { Ref, CSSProperties } from 'vue';

+export type PaperBallChargeLevel = 0 | 1 | 2 | 3;
+
 export type PaperBallThrownPayload = {
    id: string;
    from_player_id: number;
    target_player_id: number;
+    charge_level: PaperBallChargeLevel;
 };

 export type PaperBallFlightStyle = CSSProperties & {
@@ -19,9 +22,15 @@ export type PaperBallFlightStyle = CSSProperties & {

 export type PaperBallFlight = {
    id: string;
+    chargeLevel: PaperBallChargeLevel;
    style: PaperBallFlightStyle;
 };

+export type PaperBallKnockback = {
+    x: number;
+    y: number;
+};
+
 export type PaperBallTossOptions = {
    roomId: () => string;
    currentPlayerId: () => number;
@@ -1,5 +1,7 @@
 import type { CSSProperties } from 'vue';

+import type { PaperBallKnockback } from '@/types/emote';
+
 export type PokerCard = {
    key: string;
    label: string;
@@ -115,6 +117,7 @@ export type RoomSeatProps = {
    revealed: boolean;
    presenterMode: boolean;
    isPaperBallHit: boolean;
+    paperBallKnockback: PaperBallKnockback;
    throwDisabled: boolean;
 };

@@ -154,9 +157,5 @@ export type RoomStateChangedPayload = {

 export type RoomRealtimeState = Pick<
    PokerRoom,
-    | 'current_round'
-    | 'revealed'
-    | 'state_version'
-    | 'statistics'
-    | 'players'
+    'current_round' | 'revealed' | 'state_version' | 'statistics' | 'players'
 >;
@@ -20,7 +20,6 @@ function createEmoteRoom(array $attributes = []): Room
 }

 test('a participant can throw a realtime paper ball at another player', function () {
-    Event::fake([PaperBallThrown::class]);
    $room = createEmoteRoom(['last_activity_at' => now()->subDay()]);
    $sender = $room->players()->create([
        'name' => 'Eric',
@@ -33,6 +32,7 @@ test('a participant can throw a realtime paper ball at another player', function
    $room->refresh();
    $activity = $room->last_activity_at;
    $stateVersion = $room->state_version;
+    Event::fake([PaperBallThrown::class]);

    $this->withSession(["room_players.{$room->id}" => $sender->id])
        ->postJson(route('room.emote.paper-ball.store', $room), [
@@ -44,12 +44,14 @@ test('a participant can throw a realtime paper ball at another player', function
        return $event->roomId === $room->id
            && $event->fromPlayerId === $sender->id
            && $event->targetPlayerId === $target->id
+            && $event->chargeLevel === 0
            && $event->broadcastOn()->name === "rooms.{$room->id}"
            && $event->broadcastAs() === 'room.emote.thrown'
            && array_keys($event->broadcastWith()) === [
                'id',
                'from_player_id',
                'target_player_id',
+                'charge_level',
            ];
    });

@@ -59,6 +61,65 @@ test('a participant can throw a realtime paper ball at another player', function
        ->and($room->state_version)->toBe($stateVersion);
 });

+test('paper ball charge percentages map to the expected level', function (int $chargePercentage, int $expectedLevel) {
+    $room = createEmoteRoom();
+    $sender = $room->players()->create([
+        'name' => 'Eric',
+        'is_moderator' => true,
+    ]);
+    $target = $room->players()->create([
+        'name' => 'Anna',
+        'is_moderator' => false,
+    ]);
+    Event::fake([PaperBallThrown::class]);
+
+    $this->withSession(["room_players.{$room->id}" => $sender->id])
+        ->postJson(route('room.emote.paper-ball.store', $room), [
+            'target_player_id' => $target->id,
+            'charge_percentage' => $chargePercentage,
+        ])
+        ->assertNoContent();
+
+    Event::assertDispatched(
+        PaperBallThrown::class,
+        fn (PaperBallThrown $event): bool => $event->chargeLevel === $expectedLevel,
+    );
+})->with([
+    'uncharged' => [0, 0],
+    'just below level one' => [99, 0],
+    'level one threshold' => [100, 1],
+    'top of level one' => [199, 1],
+    'level two threshold' => [200, 2],
+    'top of level two' => [299, 2],
+    'level three threshold and cap' => [300, 3],
+]);
+
+test('paper ball charge percentages outside the supported range are rejected', function (int $chargePercentage) {
+    $room = createEmoteRoom();
+    $sender = $room->players()->create([
+        'name' => 'Eric',
+        'is_moderator' => true,
+    ]);
+    $target = $room->players()->create([
+        'name' => 'Anna',
+        'is_moderator' => false,
+    ]);
+    Event::fake([PaperBallThrown::class]);
+
+    $this->withSession(["room_players.{$room->id}" => $sender->id])
+        ->postJson(route('room.emote.paper-ball.store', $room), [
+            'target_player_id' => $target->id,
+            'charge_percentage' => $chargePercentage,
+        ])
+        ->assertUnprocessable()
+        ->assertJsonValidationErrors('charge_percentage');
+
+    Event::assertNotDispatched(PaperBallThrown::class);
+})->with([
+    'below zero' => -1,
+    'above the cap' => 301,
+]);
+
 test('a participant cannot throw a paper ball at themselves', function () {
    Event::fake([PaperBallThrown::class]);
    $room = createEmoteRoom();