Custom Theme Creator Guide

Overview

The Theme Creator is a powerful web-based tool that allows you to create and manage custom themes for SoulWars. With the Theme Creator, you can upload your own artwork, music, and configure how players experience your custom battle environment.

Getting Started

Accessing the Theme Creator

1

Navigate to the Theme Creator page in the SoulWars application

2

You'll see a list of your existing themes (if any)

3

Click "Create New Theme" to start a new theme

Creating Your First Theme

1

Enter a Theme Name (required, max 128 characters)

2

Add a Description (optional, max 1024 characters) to help others understand your theme

3

Click "Create Theme"

Your new theme will be created with default settings and a single "Warrior" player class.

Asset Requirements

Cover Image

The cover image is displayed when browsing themes in the shop or theme selector.

• Format: JPG only

• Aspect Ratio: 2:1 (e.g., 1200x600px or 1600x800px)

• Dimensions:

  • Minimum: 600x300px

  • Maximum: 4096x2048px

• Purpose: Main promotional image for your theme

Battlefield Maps

Battlefield maps are the background environments where battles take place.

• Format: JPG only

• Aspect Ratio: 1:1 (square)

• Dimensions:

  • Minimum: 1024x1024px

  • Maximum: 4096x4096px

• Recommendation: Use 2048x2048px for optimal quality/performance balance

• Multiple Maps: You can upload multiple battlefield maps for variety

Player Images

Player images represent the characters that fight in battles.

• Format: PNG only (for transparency support)

• Aspect Ratio: 1:1 (square)

• Dimensions:

  • Maximum input: 2048x2048px

  • Automatically resized to: 512x512px

• Transparency: PNG alpha channel is preserved

• Metadata: Each player requires:

  • Player Name: Display name (optional)

  • Class: Must match one of your theme's classes

Music Tracks

Background music plays during battles.

• Format: MP3 only

• File Size: Maximum 10MB

• Duration: Recommended 2:30 (150 seconds) for looping

• Quality: 128-192 kbps recommended

• Multiple Tracks: Upload multiple tracks for variety

Screen Images

Screen images are displayed during intermissions between battle phases.

• Format: JPG or PNG

• Aspect Ratio: 1:1 (square)

• Dimensions: Maximum 2048x2048px

• Purpose: Visual backgrounds for intermission messages

Managing Player Classes

Player classes categorize your player characters. The default "Warrior" class is always present.

Adding a Class

1

Navigate to the Player Images section

2

Find the Classes subsection

3

Enter a new class name (max 64 characters)

4

Click "Add"

Removing a Class

1

Find the class in the Classes list

2

Click the × button next to the class name

3

Note: You cannot remove the "Warrior" class

Using Classes

When uploading player images, you can assign them to specific classes. This helps organize your characters and allows the game to select appropriate characters for different scenarios.

Managing Player Taunts

Player taunts are text messages that appear in comic-style chat bubbles above characters during gameplay. Taunts add personality and atmosphere to battles.

What Are Taunts?

Taunts are short text phrases that players "say" during specific in-game events:

• Combat actions: Attacking, hitting, taking damage

• Eliminations: Killing an opponent or dying

• Behaviors: Fleeing, seeking food, picking up items

Adding Taunts to a Player

1

Navigate to the Players section

2

Click on a player to expand their details

3

Scroll to the Taunts section

4

Enter taunt text in the input field

5

(Optional) Select an Event from the dropdown

6

Press Enter or click "Add"

Event Types

Taunts can be assigned to specific events or left generic:

Event	When It Triggers	Example Taunts
Attack	Player starts attacking	"Face me!", "Here I come!"
Hit	Player damages opponent	"Take that!", "Got you!"
Hurt	Player takes damage	"Ugh!", "Not bad..."
Killed	Player eliminates someone	"Victory!", "Another one down!"
Death	Player is eliminated	"I'll be back...", "Worth it!"
Threaten	Player enters attack mode	"You're mine!", "Come here!"
Food	Player approaches food	"Nom nom!", "Snack time!"
Pickup	Player collects an item	"Nice!", "Score!"
Run	Player flees from danger	"Tactical retreat!", "Not today!"
No Event	Used as fallback	"Who's next?", "Let's go!"

Best Practices for Taunts

Text Length

• Keep taunts short and punchy (3-10 words ideal)

• Bubbles wrap at 300px width, so you have some room

• Example: "Got you!" is better than "I have successfully struck you with my weapon!"

Event Selection

• Use event-specific taunts for immersive context

  • "Take that!" works great for hit

  • "Ouch!" works well for hurt

• Use generic taunts (no event) for:

  • General personality phrases

  • Fallbacks when no event-specific taunt exists

  • Idle chatter between actions

Balanced Taunt Sets

For each player, aim for:

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

• 3-5 generic taunts for variety

• Total: 15-25 taunts per player for good coverage

Character Personality

Match taunts to your character's personality:

Aggressive Warrior:

• Attack: "Die!", "Face me!"

• Hit: "Pathetic!", "Too slow!"

• Death: "Impossible!", "This isn't over!"

Comedic Character:

• Attack: "Tickle time!", "Oops!"

• Hit: "Boop!", "Did I do that?"

• Death: "Worth it!", "I regret nothing!"

Heroic Knight:

• Attack: "For honor!", "Stand and fight!"

• Hit: "Justice prevails!", "Victory is near!"

• Death: "Tell my story...", "Avenge me!"

Frequency Considerations

Common events need repeatable taunts:

• Attack/Hit/Hurt: Simple, can repeat often

  • ✓ "Oof!", "Gotcha!", "Ugh!"

  • ✗ "This is my seventh victory in the battle of eternal glory!" (too long, too specific)

Rare events can be more dramatic:

• Killed/Death: More memorable, less repetition

  • ✓ "I am victorious!", "My legacy ends here..."

  • ✗ "Ha!" (too plain for important moment)

Visual Display

Taunts appear as:

• White speech bubbles with black borders

• Black Comic Sans text for classic comic feel

• Positioned just above player's name (5px gap, following movement)

• Duration: 2-3 seconds per bubble

• Automatic cooldown: 30-60 seconds per player

• Maximum 5 bubbles on screen at once

• Only active when 20 or fewer players alive (prevents early-game clutter)

Event badges in the theme editor show each taunt's trigger with color coding:

• 🔴 Attack, Threaten (red/orange)

• 🟡 Hit, Hurt (yellow/orange)

• 🟣 Killed, Death (purple/gray)

• 🟢 Food (green)

• 🔵 Pickup, Run (blue/indigo)

Managing Generic Theme Taunts

In addition to player-specific taunts, you can add theme-wide generic taunts that any player can use:

1

Navigate to Theme Settings (if available)

2

Find Generic Taunts section

3

Add taunts that work for all players

Generic taunts are:

• Used when players have no specific taunts

• Randomly triggered during idle moments

• Great for general battle atmosphere

Tips and Examples

Create Variety

• Don't repeat the same phrase:

  • ❌ "Take that!" (attack), "Take that!" (hit), "Take that!" (killed)

  • ✓ "Here I come!" (attack), "Got you!" (hit), "Victory!" (killed)

Match the Moment

• Consider what a player would say:

  • Attack: Aggressive, threatening → "You're mine!"

  • Hurt: Pained, surprised → "Ugh!", "That hurt!"

  • Killed: Triumphant → "Another one down!"

  • Death: Defeated, defiant → "I'll be back..."

Test Your Taunts

• Read them aloud - do they sound natural?

• Imagine them appearing rapidly during battle

• Make sure they're readable at a glance

Removing Taunts

1

Find the taunt in the player's taunt list

2

Click the × button next to it

3

The taunt is immediately removed

Example: Creating a Complete Taunt Set

Let's create taunts for "Sir Valiant," a heroic knight:

Combat Taunts:

• Attack: "En garde!", "For the kingdom!"

• Hit: "Taste my blade!", "Strike true!"

• Hurt: "A scratch!", "You dare?"

Outcome Taunts:

• Killed: "Justice prevails!", "Victory is mine!"

• Death: "Tell my tale...", "Avenge me!"

Behavior Taunts:

• Threaten: "Prepare yourself!", "Draw your weapon!"

• Food: "A moment's respite", "Fortifying!"

• Run: "Tactical retreat!", "Regroup!"

Generic Taunts:

• "For honor!", "Who's next?", "Stand ready!", "The battle rages on!"

This gives Sir Valiant 14 total taunts with good coverage across all events.

Configuring Intermission Screens

Intermission screens appear between battle phases to display information, create suspense, or allow player interaction.

Creating an Intermission Screen

1

Navigate to the Intermission Screens section

2

Click "Add Screen"

3

Configure the screen properties:

• Screen ID: Unique identifier (e.g., top10_players)

• Title: Main heading displayed

• Subtitle: Secondary text (optional)

• Duration: How long the screen displays (in seconds)

• Music: Optional background music track

Content Types

Choose the type of content to display:

Message

Simple text message display.

• Required: Message text

Message with Image

Text message with a background image.

• Required: Message text, Screen image (from uploaded screens)

Player List

Shows remaining players and their inventories.

• Options:

  • Show Inventory (yes/no)

  • Max Items Per Player Row (1-20)

Player List with Action

Player list with an interactive button.

• Options:

  • Show Inventory (yes/no)

  • Show Win Chance (yes/no)

  • Show Countdown (yes/no)

  • Max Items Per Player Row (1-20)

• Action Button:

  • Button Label (e.g., "Lock Bets")

  • Event Name (e.g., lock_bets)

Trigger Conditions

Triggers determine when an intermission screen appears.

• Trigger Type:

  • Players Remaining: Trigger based on alive player count

  • Battle Time: Trigger after elapsed seconds

• Operator:

  • ≤ (Less than or equal)

  • ≥ (Greater than or equal)

  • = (Equal)

• Value: The threshold number

Example: Display screen when players remaining ≤ 10

Reordering Screens

Use the ↑ and ↓ buttons to change the priority order of your intermission screens.

Publishing Your Theme

Making Your Theme Available

1

Complete all required assets

2

Test your theme thoroughly

3

Contact an administrator to set is_active = true for your theme

4

Once active, players can select your theme for their battles

Best Practices

Asset Creation

• Consistency: Use a cohesive art style across all assets

• Optimization: Compress images before uploading to reduce file sizes

• Testing: View assets on different screen sizes

• Naming: Use descriptive filenames for easy identification

• Quality: Use the recommended dimensions for best results

Thematic Design

• Color Palette: Choose 3-5 primary colors and stick to them

• Player Variety: Create diverse player characters

• Battle Maps: Design maps with visual interest but avoid clutter

• Music Selection: Choose tracks that match your theme's mood

• Intermissions: Plan narrative flow with intermission screens

Performance

• File Sizes: Keep music under 5MB when possible

• Image Dimensions: Use recommended sizes, not maximum

• Asset Count: Start with 3-5 of each asset type, expand as needed

• Testing: Test on lower-end devices to ensure smooth performance

Troubleshooting

Upload Failures

Problem: Asset upload fails

• Check file format matches requirements

• Verify file size is within limits

• Ensure image dimensions meet specifications

• Try a different browser if issues persist

Missing Assets

Problem: Uploaded assets don't appear

• Refresh the page

• Check that upload completed successfully

• Verify file was added to correct asset type

Theme Not Appearing

Problem: Theme doesn't show up in game

• Confirm is_active flag is set (requires admin)

• Verify at least one battlefield and player are uploaded

• Check browser console for errors

Support

For additional help or to report issues:

• Check the SoulWars documentation

• Contact the development team

---

Happy theme creating! Your custom themes bring unique experiences to the SoulWars community.