Taunt System

Overview

The chat bubble taunt system displays text messages in comic-style speech bubbles above players during gameplay. Taunts are triggered by specific in-game events (combat, death, pickups, etc.) and add personality and atmosphere to matches.

Architecture

The system is designed for extensibility and future audio taunt support:

  • TauntManager (client/src/taunts/TauntManager.js): Central manager for all taunt logic

  • Player Class (client/src/Player.js): Handles bubble rendering and positioning

  • Game Modes (client/src/modes/*.js): Trigger taunts based on combat events

  • Theme Editor (client/src/ThemeCreator.js): UI for managing taunts

Event Types

Taunts can be triggered by the following events:

Event
Description
Trigger Condition

attack

Player initiates attack

When player starts attacking another

hit

Player successfully damages opponent

When attack deals damage

hurt

Player takes damage

When player receives damage

killed

Player eliminates another player

When player scores a kill

death

Player is eliminated

When player dies

threaten

Player enters aggressive mode

When AI switches to attack behavior

food

Player seeks food

When player approaches food items

pickup

Player collects loot

When player walks over items

run

Player flees from danger

When player retreats from combat

Taunt Selection Priority

1

Player-specific event taunt

  • Taunt assigned to this player for this specific event

2

Player-specific generic taunt

  • Taunt assigned to this player with no event

3

Theme-wide generic taunt

  • Generic taunt from the theme's global taunt pool

Visual Specifications

Bubble Design

  • Background: White (#FFFFFF) with 100% opacity

  • Border: 2px solid black (#000000)

  • Corner Radius: 10px rounded corners

  • Padding: 15px on all sides

  • Depth: Dynamic depth based on player Y position (1000 + Y for bubble, +1 for text)

    • Bubbles lower on screen (closer to camera) render on top

    • Prevents overlapping bubbles from obscuring each other

    • Text always renders above its own bubble

Text Styling

  • Font: Comic Sans MS (or Comic Sans, cursive as fallback)

  • Size: 24px

  • Color: Black (#000000)

  • Alignment: Center

  • Word Wrap: 300px maximum width

  • Position: Just above player's nameText (5px gap)

Behavior

  • Duration: 2500ms (2.5 seconds)

  • Movement: Follows player sprite position in real-time

  • Auto-hide: Automatically disappears after duration expires

  • Death cleanup: Destroyed when player dies

Cooldowns and Limits

Player Count Gate

  • Taunts only appear when 20 or fewer players are alive

  • Prevents early-game spam with many players

  • Makes taunts more visible and impactful during final battles

Per-Player Cooldown

  • Minimum: 30 seconds between taunts

  • Maximum: 60 seconds between taunts

  • Randomly selected within range each time

Screen Limits

  • Maximum 5 chat bubbles visible simultaneously

  • Prevents screen clutter and maintains readability

  • Additional taunts are suppressed until bubbles clear

Generic Taunt Timer

  • Triggered every 15-30 seconds (random interval)

  • Only when screen is not at maximum bubble count

  • Only for players who are not on cooldown

  • Only when 20 or fewer players are alive

For Theme Creators

Adding Player-Specific Taunts

1

Navigate to Theme Editor > Players section

2

Click on a player to expand their details

3

In the Taunts section:

  • Enter taunt text in the input field

  • Select an event from the dropdown (optional)

  • Press Enter or click "Add"

Event Selection Guidelines

Event-Specific Taunts (select an event):

  • More immersive and contextual

  • Triggers only during that specific action

  • Example: "Take that!" for hit event

Generic Taunts (no event selected):

  • Used as fallback when no event-specific taunt exists

  • Can be triggered during idle moments

  • Example: "I'm the best!" (no event)

Best Practices

1

Balance event-specific and generic taunts

  • 2-3 taunts per important event (attack, hit, killed, death)

  • 3-5 generic taunts for variety

2

Keep text concise

  • Aim for 3-10 words

  • Bubble auto-sizes but wraps at 200px width

3

Match character personality

  • Aggressive characters: combat-focused taunts

  • Comedic characters: funny or ironic taunts

  • Heroic characters: noble or encouraging taunts

4

Consider event frequency

  • Common events (attack, hurt): simple, repeatable taunts

  • Rare events (killed, death): more dramatic taunts

Example Taunt Sets

Warrior Character:

  • Attack: "Face me!", "Here I come!"

  • Hit: "Take that!", "Got you!"

  • Hurt: "Ugh!", "Not bad..."

  • Killed: "Victory is mine!", "Another one down!"

  • Death: "I'll be back...", "This isn't over!"

  • Generic: "Who's next?", "Come at me!"

Comedic Character:

  • Attack: "Oops, did I do that?", "Tickle time!"

  • Hit: "Boop!", "Gotcha nose!"

  • Hurt: "Owie!", "That tickles!"

  • Killed: "I won?!", "Accidental win!"

  • Death: "Worth it!", "I meant to do that!"

  • Generic: "La la la~", "Having fun yet?"

For Developers

TauntManager API

Constructor

new TauntManager(scene, theme)

  • scene: Phaser game scene instance

  • theme: Theme data object containing taunt configuration

Methods

assignPlayerTaunts(player, textureKey)

  • Assigns taunts from theme to a player instance

  • Groups taunts by event for efficient lookup

  • Called during player spawning

triggerTaunt(player, event)

  • Attempts to trigger a taunt for a player event

  • Checks cooldowns and screen limits

  • Selects appropriate taunt based on priority

  • Parameters:

    • player: Player instance

    • event: Event string (see Event Types)

triggerRandomGenericTaunt()

  • Shows a random generic taunt on an eligible player

  • Called automatically by the update loop

  • Respects cooldowns and limits

update(delta)

  • Called each frame from Game.jsx

  • Manages generic taunt timer

  • Parameters:

    • delta: Time elapsed since last frame (ms)

onBubbleHidden(player)

  • Callback when a bubble completes its duration

  • Decrements active bubble counter

  • Internal method, called by Player

Player Class API

showTaunt(tauntText, duration, onComplete)

  • Creates and displays a chat bubble

  • Parameters:

    • tauntText: String to display

    • duration: How long to show (ms), default 2500

    • onComplete: Callback when bubble is hidden

hideTaunt()

  • Immediately hides and destroys current bubble

  • Calls onComplete callback if set

  • Called automatically after duration

updateTauntPosition()

  • Updates bubble position to follow player

  • Called each frame from Player.updateVisualComponents()

Adding New Event Triggers

1

Identify the event location in game code

2

Check if player is alive

3

Call:

scene.tauntManager?.triggerTaunt(player, 'event_name')

Example:

// In combat code
if (player.collected item) {
  // Existing item pickup logic...
  
  // Trigger taunt
  if (scene.tauntManager) {
    scene.tauntManager.triggerTaunt(player, 'pickup');
  }
}

Database Schema

Taunts are stored in theme_player_taunts table:

CREATE TABLE theme_player_taunts (
  id INT AUTO_INCREMENT PRIMARY KEY,
  theme_id VARCHAR(36) NOT NULL,
  player_id INT NOT NULL,
  taunt_text VARCHAR(255) NOT NULL,
  event VARCHAR(32) NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (theme_id) REFERENCES themes(id) ON DELETE CASCADE,
  FOREIGN KEY (player_id) REFERENCES theme_players(id) ON DELETE CASCADE
);

Generic theme taunts in theme_taunts table:

CREATE TABLE theme_taunts (
  id INT AUTO_INCREMENT PRIMARY KEY,
  theme_id VARCHAR(36) NOT NULL,
  taunt_text VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (theme_id) REFERENCES themes(id) ON DELETE CASCADE
);

Future Enhancements

Audio Taunt Support (Planned)

The architecture is designed to support audio taunts:

1

Database: Add audio_file column to theme_player_taunts

2

TauntManager: Load and play audio files

3

Player: Synchronize bubble with audio duration

4

Theme Editor: Upload audio files alongside text

Potential Features

  • Combo taunts: Special taunts for kill streaks

  • Proximity taunts: Only visible to nearby players

  • Team taunts: Coordinated taunts between teammates

  • Animated bubbles: Fade in/out, bounce effects

  • Custom styling: Per-player bubble colors/fonts

  • Taunt replies: Players can respond to each other

Troubleshooting

Taunts Not Appearing

1

Check theme data: Verify taunts exist in theme API response

2

Check console: Look for TauntManager initialization logs

3

Check cooldowns: Player might be on cooldown

4

Check limits: Screen might have 5 bubbles already

5

Check events: Ensure event name matches exactly

Bubbles Not Following Players

  • Verify updateTauntPosition() is called in Player.updateVisualComponents()

  • Check that tauntBubble and tauntText objects exist

Performance Issues

  • Reduce max bubbles from 5 to 3

  • Increase cooldown from 30-60s to 60-90s

  • Increase generic taunt interval from 15-30s to 30-60s

Support

For questions or issues:

  • Check Theme Creator Guide

  • Review Theme System Architecture

  • Contact: SoulWars development team

PreviousRewards System