Entitlements User Guide

Overview

Welcome to the SoulWars Entitlements System! This guide explains how to manage user access to game features, themes, and tools through the admin interface.

What Are Entitlements?

Entitlements are permissions that control what users can access in SoulWars. Think of them as digital keys that unlock specific features.

Default Entitlements

game_access

• Allows users to launch matches

• Enables game mode selection

• Unlocks chat features

• Required for core gameplay

theme_creator

• Grants access to the Theme Creator tool

• Allows creating and customizing visual themes

• For content creators and designers

Theme-Specific Entitlements

• Format: theme:theme-id

• Example: theme:cyberpunk-2077

• Controls access to premium/custom themes

• Note: The default soulwars-default theme is always accessible

Entitlement Categories

Game Features

• Core gameplay functionality

• Match creation and joining

• Game modes and special features

Themes

• Visual customizations

• Battlefield appearances

• UI styling

Tools

• Development and creation tools

• Theme Creator

• Future admin tools

Admin Panel Access

Requirements

To access the admin panel, you must have one of these permission levels:

• admin

• moderator

• super_admin

Accessing the Panel

1

Connect and Open Admin

• Connect your wallet in the top navigation

• Click the menu icon (≡) in the top right

• Select "Admin" from the menu

2

Admin Panel

You'll see the Admin Panel with three tabs:

┌─────────────────────────────────────────────────┐
│          SoulWars Admin Panel                   │
├─────────────────────────────────────────────────┤
│  Grant Entitlement | View User | Manage         │
├─────────────────────────────────────────────────┤
│                                                 │
│  [Current tab content here]                     │
│                                                 │
└─────────────────────────────────────────────────┘

Granting Access

Basic Grant Flow

1

Find the User

• Go to the "Grant Entitlement" tab

• Enter search criteria:

  • Wallet address (e.g., 7xKXt...)

  • Username

  • Email address

• Click "Search"

• Select the user from the results

2

Choose Entitlement

• From the "Entitlement" dropdown, select what to grant:

  • Game Access

  • Theme Creator Access

  • Specific theme access

• Review the description to confirm it's correct

3

Configure Grant Details

• Grant Type: Select how this access was obtained

  • Admin Grant: You're giving them access

  • Trial: Temporary trial period

  • Gift: Given as a reward or promotion

  • Purchased: They bought it (usually automatic)

  • Creator: For content creators

• Expiration Date (Optional):

  • Leave blank for permanent access

  • Set a date/time for temporary access

• Notes (Optional):

  • Add context for why access was granted

  • Example: "Beta tester - Phase 1"

4

Grant

• Click "Grant Entitlement"

• Wait for success confirmation

• User immediately has access (may need to refresh their page)

Example: Giving a User Game Access

User Search: 7xKXtGh8...
↓
Select: John Doe (7xKXt...xyz)
↓
Entitlement: Game Access
Grant Type: Admin Grant
Expires At: [blank] (permanent)
Notes: "New player onboarding"
↓
Click: Grant Entitlement
↓
✓ Success!

Managing User Entitlements

Viewing a User's Entitlements

1

Open View Tab

• Go to "View User Entitlements" tab

• Enter the User ID (found in search results)

• Click "View"

2

Review Entitlements

See all active entitlements for that user. For each entitlement, you'll see:

• Name (e.g., "Game Access")

• Description

• ID (technical identifier)

• Type (how it was granted: admin, trial, etc.)

• Category (game_feature, theme, or tool)

• Granted (when it was given)

• Expires (when it expires, if applicable)

• Notes

Revoking Access

Revoking is immediate and cannot be undone. The user will lose access right away.

1

Revoke Entitlement

• View the user's entitlements (as above)

• Find the entitlement to remove

• Click the red "Revoke" button

• Confirm the action

• Entitlement is immediately removed

Creating New Entitlements

When to Create New Entitlements

Create a new entitlement when you need to:

• Launch a new premium theme

• Add a new game feature that requires access control

• Create a new tool or capability

• Set up a new tier of access

How to Create

1

Open Manage Tab

• Go to "Manage Entitlements" tab

• Scroll to "Create New Entitlement" form

2

Fill Details

Required and recommended fields:

• Entitlement ID (Required)

  • Technical identifier used in code

  • Must be unique

  • Format rules:

    • Game features: lowercase with underscores (e.g., tournament_access)

    • Themes: theme:theme-id (e.g., theme:neon-nights)

    • Tools: descriptive name (e.g., map_editor)

  • Cannot be changed after creation

• Name (Required)

  • Human-readable display name

• Description (Optional but recommended)

  • Explain what this entitlement provides

• Category (Required)

  • Select one: Game Feature, Theme, Tool

3

Create

• Click "Create Entitlement"

• New entitlement appears in the list below

• Now available in the "Grant Entitlement" dropdown

Example: Creating a Theme Entitlement

Creating entitlement for new "Cyberpunk 2077" theme:

Entitlement ID: theme:cyberpunk-2077
Name: Cyberpunk 2077 Theme
Description: Futuristic neon-lit battlefield theme with synthwave aesthetics
Category: Theme

→ Click "Create Entitlement"
→ ✓ Created successfully!
→ Now can grant to users

Common Scenarios

Scenario: Onboarding a New Player

1

Search for their wallet address

2

Grant "Game Access" entitlement

3

Grant Type: Admin Grant; Leave expiration blank (permanent); Notes: "New player onboarding - [Date]"

Result: Player can now launch matches and play games.

Scenario: Beta Testing a New Theme

1

Create theme entitlement:

• ID: theme:beta-theme-v1

• Name: "Beta Theme v1"

• Category: Theme

2

For each tester:

• Grant the theme entitlement

• Grant Type: Trial

• Expires At: [30 days from now]

• Notes: "Beta tester - Group A"

Result: Testers can use the theme for 30 days, then access automatically expires.

Scenario: Rewarding Content Creators

1

Search for creator's wallet

2

Grant "Theme Creator" entitlement

• Grant Type: Creator

• No expiration

• Notes: "Verified content creator - Application #123"

Result: User sees "Theme Creator" link in menu and can access the tool.

Scenario: Limited-Time Promotion

1

For each promotional user:

• Grant "Game Access"

• Grant Type: Gift

• Expires At: [7 days from now]

• Notes: "Launch week promotion"

Result: Users have access for exactly 1 week, then it expires automatically.

Scenario: Theme Creator Needs Their Own Theme

1

Create theme entitlement:

• ID: theme:artist-theme-name

• Name: "[Artist Name]'s Theme"

• Category: Theme

2

Grant to creator:

• Type: Creator (or Owned)

• No expiration

• Notes: "Theme creator - owns this theme"

3

Grant to any buyers/users as needed

Result: Creator can always use their theme, others need to be granted access.

Troubleshooting

Below are common issues and checks. Each entry is collapsible for convenience.

User Says They Can't Access a Feature

Checklist:

1. Does the user have the required entitlement? — View their entitlements in admin panel

2. Is the entitlement expired? — Check "Expires" date

3. Has the user refreshed their page? — Tell them to reload the website

4. Is the user logged in with the correct wallet? — Verify wallet address matches

Fix:

• Grant missing entitlement

• Extend expiration date if needed

• Ask user to reconnect wallet

Grant Fails with "User already has this entitlement"

Cause: User already has an active (non-expired) entitlement

Solutions:

1. View the user's entitlements to see existing grant

2. If you want to extend it: revoke the old one, then grant a new one with new expiration

3. If it's expired, it should allow re-granting (if not, database issue)

Can't Access Admin Panel

Possible Causes:

• Not logged in: Connect your wallet first

• Wrong wallet: Make sure you're using an admin wallet

• No admin permission: Your user account doesn't have admin status

Fix:

• Verify your user ID has an entry in permissions table

• Permission level must be: admin, moderator, or super_admin

• Contact a super admin to grant you permissions

Theme Entitlement Not Working

Checklist:

1. Entitlement ID follows format: theme:theme-id

2. Theme ID matches exactly (case-sensitive)

3. User has the entitlement (not expired)

4. Theme exists in the system

Common Mistake:

❌ Wrong: theme_cyberpunk_2077
✓ Right: theme:cyberpunk-2077

The colon (:) is required for theme entitlements.

Entitlement Granted But User Still Locked Out

Steps:

1. Confirm entitlement appears in database: view user's entitlements in admin panel

2. Ask user to:

   • Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)

   • Clear browser cache

   • Disconnect and reconnect wallet

3. Check browser console for errors (F12)

If still not working:

• Frontend may not be checking for entitlement correctly

• Report to development team with:

  • User ID

  • Entitlement ID

  • Browser and wallet used

Best Practices

For Granting Entitlements

1. Always add notes explaining why access was granted — helps with auditing and record-keeping.

2. Use appropriate grant types:

   • Admin: Manual grants

   • Trial: Testing/temporary access

   • Gift: Promotions and rewards

   • Purchased: Payment-based (usually automatic)

3. Set expiration dates for trials to avoid forgotten permanent access.

4. Double-check user before granting — verify wallet address or username.

For Managing Entitlements

1. Regularly review active entitlements — check for expired access and remove test accounts.

2. Document new entitlements — clear descriptions and consistent naming.

3. Communicate with users — notify when access is granted or revoked and provide support.

Getting Help

For Users

If a user contacts you about entitlement issues:

1. Check their entitlements in the admin panel

2. Verify expiration dates

3. Ask them to refresh/reconnect wallet

4. Grant or extend entitlement if appropriate

For Admins

If you need technical help:

• Check Entitlements System Architecture for developer docs

• Contact development team for:

  • New entitlement categories

  • Custom entitlement logic

  • Database issues

  • Permission problems

Appendix: Entitlement ID Reference

Current Default Entitlements

ID	Name	Category	Purpose
game_access	Game Access	game_feature	Launch matches, use chat, play game
theme_creator	Theme Creator Access	tool	Access theme creation tool
theme:soulwars-default	-	-	No entitlement needed (always accessible)

Naming Conventions

Game Features:

• Format: feature_name or game_feature_name

• Examples: tournament_access, ranked_matches, spectator_mode

Themes:

• Format: theme:theme-id

• Examples: theme:cyberpunk-2077, theme:medieval-fantasy, theme:space-station

• Theme ID should match the theme's technical ID in the system

Tools:

• Format: tool_name or descriptive identifier

• Examples: map_editor, replay_analyzer, tournament_organizer

ID Guidelines

• Use lowercase

• Use hyphens for themes: theme:my-theme-name

• Use underscores for features: my_feature_name

• Be descriptive and concise

• No spaces; only hyphens and underscores as special characters

Conclusion

The Entitlements System gives you powerful control over user access to SoulWars features. By following this guide, you can effectively manage permissions, create new access types, and provide a great experience for your users.

Remember: Entitlements are instantly active when granted and instantly removed when revoked. Always double-check before taking action!

For technical implementation details, see the Architecture Documentation.