django-word-battle

A reusable Django REST Framework + Channels backend for competitive multiplayer word-change games. Players take turns changing letters (FALL → CALL → TALL), and a player loses when they have no legal move, run out of time or resign.

The product name is not hard-coded. Set WORD_BATTLE["GAME_NAME"] or the WORD_BATTLE_GAME_NAME environment variable and the API, admin, emails and API docs use it. The Python package keeps the neutral import name word_battle.

pip install "django-word-battle[all]"

What's inside

Real-money wagering, deposits, cash-out and paid-entry cash prizes are not implemented. Sponsored real-world prizes are blocked by a database constraint until legal approval, an app-store policy review and official rules are recorded. They also need the real_world_prizes flag, which can only be turned on in the admin.

Quick start (existing Django project)

# settings.py
INSTALLED_APPS += ["rest_framework", "channels", "word_battle"]
ASGI_APPLICATION = "config.asgi.application"
CHANNEL_LAYERS = {"default": {"BACKEND": "channels_redis.core.RedisChannelLayer", "CONFIG": {
    "hosts": [{"address": "redis://localhost:6379/0", "socket_timeout": 30}]}}}
REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": ["rest_framework_simplejwt.authentication.JWTAuthentication"],
    "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.IsAuthenticated"],
    "EXCEPTION_HANDLER": "word_battle.api.exceptions.exception_handler",
}
WORD_BATTLE = {"GAME_NAME": "Word Clash"}

# urls.py
path("api/v1/", include("word_battle.api.urls")),

# asgi.py
from word_battle.realtime.middleware import OriginOrNativeValidator, WordBattleAuthMiddlewareStack
from word_battle.realtime.routing import websocket_urlpatterns
application = ProtocolTypeRouter({
    "http": get_asgi_application(),
    "websocket": OriginOrNativeValidator(WordBattleAuthMiddlewareStack(URLRouter(websocket_urlpatterns))),
})

python manage.py migrate
python manage.py wb_setup_defaults      # dictionary (ENABLE), modes, rewards, achievements, cosmetics, flags, start words
celery -A config worker & celery -A config beat   # or: python manage.py wb_worker

Set app.conf.beat_schedule = word_battle.tasks.BEAT_SCHEDULE in your Celery app. The schedule covers turn timeouts every 1 s, matchmaking every 2 s, and the daily challenge, housekeeping and anti-cheat scans.

To run the complete example stack with Docker:

cp .env.example .env
docker compose up --build        # API on :8000, docs at /api/docs/, admin at /admin/

Configuration

All keys are optional. Nested dicts are merged with the defaults; see src/word_battle/conf.py for every key.

The package also sends Django signals: match_completed, move_accepted, purchase_verified, reward_granted and achievement_unlocked, all from word_battle.signals.

Management commands

Documentation

• docs/api.md: REST endpoints, error codes, idempotency
• docs/realtime.md: WebSocket protocol and event catalogue
• docs/flutter-integration.md: client integration guide
• docs/monetization.md: store, ads and sponsored-campaign setup and compliance limits
• docs/deployment.md: production setup, scaling, backups, runbooks
• docs/release-checklist.md: Google Play and App Store release checklist
• docs/openapi.yml: generated OpenAPI 3 schema. With drf-spectacular, /api/docs/ serves it live.

Development

pip install -e ".[dev]"
createdb word_battle    # tests need PostgreSQL (row locks, SKIP LOCKED); set DATABASE_URL if different
pytest                  # 109 tests: engine, services, API, WebSockets, real concurrency
ruff check src tests example_project
python scripts/smoke_test.py --base http://localhost:8000   # end-to-end against a running stack

Licence

MIT. The bundled ENABLE word list is in the public domain. A "common words" list is not bundled, because the popular frequency lists are not licensed for commercial use. Supply your own with wb_import_dictionary --common.