Documents

Meta Login Plugin – Installation and Usage Guide

This guide explains how to install, configure, and use the Meta Login plugin in an Unreal Engine game project. It also documents the key classes/functions you will interact with and details the user data structure used by the plugin. Replace the screenshot placeholders with your own images.

Demo Content Notice

• The included levels L_Login, L_Lobby, and L_Game are provided for quick testing only. They demonstrate the login → lobby → gameplay flow. For production, create and use your own levels.
• Sample login and main menu widgets in Plugins/MetaLogin/Content/UI/ are also for testing. For your shipped game, build your own WBP_LoginScreen and WBP_MainMenu tailored to your project.

Who Is This For? What Do I Get?

• If you want a plug-and-play login flow to test quickly, this plugin gives you a working example with clear entry points to extend.
• You get: settings panel, helper Blueprint/C++ classes, demo levels/widgets, and a ready-to-run Django backend for local testing.
• You keep full control: replace demo content with your own levels, widgets, and visuals when moving to production.

Quick Start – Create Required Levels and UI Widgets

• Required Levels
• Create three levels in your project and save them as:
  • L_Login – used for the login flow
  • L_Lobby – used as a landing/lobby level after login
  • L_Game – your gameplay level (or any main game level)
• In Project Settings → Maps & Modes, set your default maps as needed (e.g., Editor Startup Map to L_Login, Game Default Map to L_Login initially). You can later transition to L_Lobby or L_Game after successful login via settings or Blueprint logic.
• Required UI Widgets
• Create WBP_LoginScreen and WBP_MainMenu widgets in your project (e.g., under Content/UI/).
• Model these after the examples provided by the plugin (see Plugins/MetaLogin/Content/UI/). The WBP_LoginScreen should collect credentials and call the GameInstance’s login/register functions; the WBP_MainMenu should present post-login options (e.g., play/continue, logout).
• In Project Settings → Game → Meta Login, assign:
  • Login Screen Widget Class → WBP_LoginScreen
  • Main Menu Widget Class → WBP_MainMenu
• If desired, you can duplicate the sample login widget from the plugin content and adapt it to your project style.

1) Requirements

• Unreal Engine: 5.6.0
• Platform: Win64 (per plugin Whitelist)
• Optional: Python 3.12+ to run the bundled Django backend.

2) Install the Plugin

1. Copy the MetaLogin plugin folder into your project under Plugins/.
2. Launch your project and ensure the plugin is enabled.

3) Configure Project Classes

Set your project to use the plugin’s base classes (or inherit from them in Blueprint):
- Project Settings → Maps & Modes
- GameInstance Class: UMetaGameInstance
- Default GameMode (or level override): AMetaGameMode

4) Configure Plugin Settings

Project Settings → Game → Meta Login.

Backend Connection

• Backend API URL: e.g. http://localhost:9711
• API Token Endpoint: /api/token/
• API Token Refresh Endpoint: /api/token/refresh/
• Game Register Endpoint: /api/game/register/
• Game Login Endpoint: /api/game/login/
• Game Logout Endpoint: /api/game/logout/
• Game Profile Endpoint: /api/game/profile/
• Connection Timeout / Request Retry Count

Authentication

• Remember User, Enable Offline Mode, Allow Guest Login, Auto Login Timeout

Session

• Max Concurrent Players, Session Update Interval, Auto Save Interval

Game

• Enable Leaderboard, Starting Currency, Experience Per Level, Guest Starting Currency
• MMO Level Name (used by guest spectator flow)

UI

• Login Screen Widget Class, Main Menu Widget Class

Flow

• Auto Transition To Level After Login, Post Login Level Name, Show Main Menu After Login

Notes:
- The plugin composes full URLs from the base Backend API URL and the endpoints above.
- Ensure endpoints include leading slashes (e.g., /api/game/login/).

5) Setting Up the Backend (Django)

Repository: MetaLoginBackend (GitHub)

The backend is hosted separately on GitHub and needs to be downloaded and set up independently from the plugin.

5.1) Download and Setup Steps (Windows):

1. Clone the backend repository:
   
   git clone https://github.com/Asha-Empire/meta-login-backend.git

cd meta-login-backend
   

2. Set up Python environment:
   
   python -m venv .venv

.venv\Scripts\activate.ps1

# or

.venv\Scripts\activate.bat
   

3. Install dependencies and run:
   
   pip install -r requirements.txt

python manage.py makemigrations

python manage.py migrate

python manage.py runserver 0.0.0.0:9711
   

Configuration:
- meta_project/settings.py loads config_dev.toml by default (SQLite, permissive CORS).
- For production, point the loader to config.toml and set allowed_hosts, DB, Redis, and host_port.
- If you change the host/port, update Backend API URL in Project Settings.

5.2) Deploying the Backend (Production/Staging)

The backend repository contains a ready-to-run Django API. You can deploy it to your own server or a managed platform.

Recommended targets
- Linux VM (Ubuntu 22.04+), a Docker container, or a PaaS (e.g., Render/Fly/railway.app)

Ubuntu VM (minimal example)
1) Clone the repository on the server:

git clone https://github.com/Asha-Empire/meta-login-backend.git

cd meta-login-backend

2) Install Python 3.12+, then:
python -m venv .venv

. .venv/bin/activate

pip install -r requirements.txt

3) Configure production settings in config.toml:
- allowed_hosts = ["your-domain.com", "www.your-domain.com"]
- Set your database (PostgreSQL recommended) and optional Redis URL
- host_port = "0.0.0.0:8000"
4) Initialize and collect assets:
python manage.py makemigrations

python manage.py migrate

python manage.py collectstatic --no-input

5) Start a production server (example Gunicorn):
gunicorn meta_project.wsgi:application --bind 0.0.0.0:8000 --workers 2

6) Put Nginx (or another reverse proxy) in front:
- Proxy https://your-domain.com → http://127.0.0.1:8000
- Enable HTTPS (e.g., Let’s Encrypt)
7) In Unreal Project Settings → Meta Login, set Backend API URL to https://your-domain.com

Docker (very short outline)
- Build an image that runs gunicorn meta_project.wsgi:application and expose 8000.
- Optionally add Nginx as a second container for TLS/HTTP/2 and static file serving.

Notes
- Use config.toml for production; keep secrets in env vars or a secret manager.
- Ensure CORS and allowed_hosts include your game clients and editor machine if testing remotely.
- If you change ports/paths on the server, mirror them in the plugin’s endpoint settings.

API Endpoints used by the plugin:
- POST /api/token/ → returns { access, refresh }
- POST /api/token/refresh/ → { access, refresh }
- POST /api/game/register/ (Bearer)
- POST /api/game/login/ (Bearer)
- GET /api/game/profile/ (Bearer)
- POST /api/game/logout/ (Bearer)

Quick Reference

First Run Checklist (about 15 minutes)

• [ ] Enable the plugin; set UMetaGameInstance and AMetaGameMode in Maps & Modes
• [ ] Clone backend from GitHub: git clone https://github.com/Asha-Empire/meta-login-backend.git
• [ ] Setup backend: create venv, install requirements, migrate, run server at http://localhost:9711
• [ ] Project Settings → Meta Login: set API URL; ensure endpoints start with /
• [ ] Assign widgets: Login = WBP_LoginScreen, Main Menu = WBP_MainMenu
• [ ] Play L_Login → Register → Login → see Main Menu/Lobby → transition to gameplay

6) Typical UI Flow

AMetaGameMode manages login and main menu UI based on settings:
- On BeginPlay, shows Login Screen if login is required and not already logged in.
- On successful login: hides Login Screen; shows Main Menu or auto-opens Post Login Level if configured.
- Guest flow: if Allow Guest Login is enabled, calling LoginAsGuest() opens MMOLevelName and switches the player to spectator mode.

Note: LoginAsGuest() does not require the backend server to be running. You can use it offline to quickly test the guest/spectator flow.

Example Widget Blueprints – Explained

• Login & Register (second screenshot):
• On Clicked (LoginButton): Get Game Instance → Cast to UMetaGameInstance → read Username/Password text boxes → call LoginUser(Username, Password).
• On Clicked (GuestLoginButton): Get Game Instance → Cast to UMetaGameInstance → call LoginAsGuest().
• On Clicked (RegisterButton): Get Game Instance → Cast to UMetaGameInstance → read Username/Email/Password/PasswordConfirm/DisplayName → call RegisterUser(...).

• Tip: bind OnLoginSuccess/OnLoginFailed and OnRegisterSuccess/OnRegisterFailed to show success/error messages and switch UI states.

• Notification/Status (first screenshot):

• Custom events ShowNotification(Message, Duration) and HideNotification() control a small banner/toast.
• ShowNotification sets the text, plays a "Fade In" animation, and optionally starts a timer to auto-hide.
• HideNotification plays a "Fade Out" animation; after a short delay it removes the widget (or collapses it).
• Use this to surface errors from login/register or general status updates.

7) Using the Classes and Functions

7.1 UMetaGameInstance

GameInstance implementation for Meta Login (Blueprintable).

Key callable functions:

Authentication / Login

• GetAuthenticationToken() → Requests a short-lived access/refresh token from the backend.
• LoginUser(Username, Password) → Orchestrates token then login flow.
• RegisterUser(Username, Email, Password, PasswordConfirm = "", DisplayName = "") → Token + registration flow.
• LogoutUser() → Clears local state and broadcasts OnUserLogout.
• LoginAsGuest() → Enters guest spectator mode using MMOLevelName.

Data and Config

• IsUserLoggedIn(), IsGuestMode()
• GetCurrentUserData() / SetCurrentUserData(UserData)
• GetAuthToken(), GetAccessToken(), GetRefreshToken()
• SetAPIEndpoint(NewEndpoint), GetAPIEndpoint()
• IsGuestLoginAllowed(), IsOfflineModeEnabled()
• GetStartingCurrency(), GetGuestStartingCurrency()

Multiplayer/MMO stubs

• CreateMultiplayerSession(...), FindMultiplayerSessions(), JoinMultiplayerSession(...), DestroyCurrentSession()
• ConnectToMMOServer(Address, Port), DisconnectFromMMOServer(), IsConnectedToMMOServer()

Events (Blueprint-assignable):
- OnLoginSuccess(FMetaUserData) / OnLoginFailed(FString)
- OnRegisterSuccess(FString) / OnRegisterFailed(FString)
- OnUserLogout()
- Token events: OnTokenReceived(Access, Refresh), OnTokenFailed(Error)
- Guest spectator: OnGuestSpectatorModeStarted(FMetaUserData)
- MMO: OnMMOConnectionSuccess, OnMMOConnectionFailed, OnMMODisconnected

Usage snippet (Blueprint logic in prose):
- From your Login Widget, get GameInstance → cast to UMetaGameInstance → call LoginUser(Username, Password). Bind to OnLoginSuccess/OnLoginFailed.

Step-by-step: Build Your Own Widgets (simple path)
1) Duplicate the sample WBP_LoginScreen into your project (or create a new Widget BP).
2) Add Username/Password fields and a Login Button.
3) On Button Click:
- Get GameInstance → Cast to UMetaGameInstance → Call LoginUser(Username, Password)
- Bind OnLoginSuccess to hide the login widget and show your main menu.
- Bind OnLoginFailed to display the error string to the user.
4) For Register, call RegisterUser(...) with your form fields (after token retrieval handled by the instance).
5) Assign these widget classes in Project Settings → Game → Meta Login.

7.2 AMetaGameMode

GameMode handling login/main menu widgets and high-level flow.

Key callable functions:
- UI: ShowLoginScreen(), HideLoginScreen(), ShowMainMenu(), HideMainMenu(), TransitionToGameplay(GameLevel)
- MMO server admin stubs: InitializeMMOServer(), ShutdownMMOServer(), BroadcastServerMessage(Message), KickPlayer(Player, Reason)

Overridable Blueprint events:
- OnUserLoginSuccess(UserData)
- OnUserLoginFailed(ErrorMessage)
- OnUserLogoutEvent(PlayerController)
- Native events: HandlePlayerLogin(PlayerController, UserData), HandlePlayerLogout(PlayerController)

7.3 AMetaGameSession

Session actor integrating with authentication events and basic player tracking.

Highlights:
- Binds token/login event callbacks from UMetaGameInstance.
- Maintains active player list and caps by MaxConcurrentPlayers.

7.4 AMetaGameState

Replicates basic server state, player list, and supports a simple leaderboard toggle.

Highlights:
- SetServerMessage(Message), GetTopPlayers(Count), UpdatePlayerScore(PlayerId, Score)

7.5 UMetaLoginBlueprintLibrary

Convenience accessors for settings and small utilities.

Common functions:
- URLs: GetBackendAPIURL(), GetFullLoginURL(), GetFullRegisterURL(), GetFullTokenURL(), GetFullLogoutURL(), GetFullProfileURL()
- Settings: GetConnectionTimeout(), GetRetryCount(), IsGuestLoginAllowed(), IsOfflineModeEnabled(), GetAutoLoginTimeout()
- Game: IsLeaderboardEnabled(), GetStartingCurrency(), GetExperiencePerLevel(), GetGuestStartingCurrency()
- Debug: IsExtendedLoggingEnabled(), ShouldUseMockBackend(), ShouldShowDebugMessages(), LogMessage(Message, bIsError), ShowDebugMessage(Message, Duration, Color)

Advanced/MMO Features Status

• Multiplayer/MMO functionality in this plugin is stubbed in this release. Function signatures and events exist for future expansion.
• To use in production, integrate with your own session backend/MMO server or extend the provided classes.

8) FMetaUserData Structure

The plugin uses FMetaUserData to represent the logged in (or guest) user. Below fields are available for BP/C++:

Identity

• ID (int32)
• UserID (string)
• Username (string)
• Email (string)
• bIsActive (bool)
• DisplayName (string)

Character & Progression

• CharacterName (string)
• Level (int32)
• Experience (int32)

Currency & Stats

• Currency (int32) – convenience, mirrors Coins
• Coins (int32)
• Gems (int32)
• HealthPoints / MaxHealthPoints (int32)
• Energy / MaxEnergy (int32)

Gameplay

• CurrentStage (int32)
• AchievementsUnlocked (int32)
• RankTier (string)
• TotalPlaytimeMinutes (int32)
• GamesPlayed (int32), GamesWon (int32), HighestScore (int32)
• FriendsCount (int32), GuildName (string)

Session

• AuthToken (string) – current access token (if logged in)
• LastLoginTime (FDateTime)

The backend GameAccount model maps to these fields; the plugin fills FMetaUserData from the /api/game/login/ response and sets AuthToken to the retrieved access token.

9) Example Backend Requests (for reference)

Token (no auth):
POST /api/token/

{ "username": "<gen>", "password": "<gen>", "day": "monday", "month": "january", "random": "12345678" }

Login (Bearer):
POST /api/game/login/

Authorization: Bearer <access>

{ "username": "player123", "password": "secretpw" }

Register (Bearer):
POST /api/game/register/

Authorization: Bearer <access>

{ "username": "player123", "email": "player@example.com", "password": "secretpw", "password_confirm": "secretpw", "display_name": "PlayerOne" }

Profile (Bearer): GET /api/game/profile/

Logout (Bearer): POST /api/game/logout/ with { "refresh_token": "<jwt-refresh>" }

10) Troubleshooting

Connection / 404

• Backend API URL incorrect or endpoints missing leading /. Default: http://localhost:9711.

401 Unauthorized

• Token/Authorization missing or expired. Obtain token first; plugin sends Bearer automatically for game endpoints.
• System time skew can break token derivation. Check OS time/locale.

Server will not start

• Ensure you've cloned the backend: git clone https://github.com/Asha-Empire/meta-login-backend.git
• Navigate to backend folder: cd meta-login-backend
• Activate venv: .venv\Scripts\activate.ps1 or .venv\Scripts\activate.bat
• Install deps: pip install -r requirements.txt
• Run migrations: python manage.py migrate

Port conflict

• Try another port: python manage.py runserver 0.0.0.0:9720
• Update Project Settings → Backend API URL to match.

CORS / Allowed Hosts

• Dev: config_dev.toml. Prod: set allowed_hosts, DB, and host_port in config.toml.

Windows Firewall / Antivirus

• May block local server. Allow the app or use a different port.

SQLite locked

• Another process holds the DB. Stop the server, retry.

Pip / Python PATH

• If pip not recognized, fix PATH. Python 3.12 recommended.

Demo Levels Not Loading (Black Screen Issue)

If demo levels (L_Game, L_Lobby) show only a loading screen or fade to black:

Common Causes:
1. Level Path Issues: Plugin levels may not be properly mounted or referenced
2. Project Settings: Auto-transition settings may be misconfigured
3. Asset Registry: Level assets not properly registered

Solutions:
1. Check Project Settings → Meta Login → Flow:
- Set Post Login Level Name to L_Game (without path)
- Enable Auto Transition To Level After Login
- Enable Show Main Menu After Login if you want menu first

1. Manual Level Transition (Blueprint):
   
   // In your login widget or game mode

Get Game Instance → Cast to MetaGameInstance → Get Current User Data

// If logged in successfully:

Call Function: Meta Login Blueprint Library → Transition To Level

Level Name: "L_Game"

Show Loading Screen: true
   

2. Check Console Logs:
   - Look for TransitionToGameplay: messages
   - Check for Failed to load level or Package not found errors
   - Enable Extended Logging in Project Settings → Meta Login → Debug

3. Verify Level Paths:
   - Ensure demo levels exist in Plugins/MetaLogin/Content/Level/
   - Use Blueprint function Get Available Levels to see what's detected
   - Try using Is Level Valid to test level names

4. Alternative Level Names:
   - Try full paths: /MetaLogin/Level/L_Game
   - Or: /Game/MetaLogin/Level/L_Game
   - Or copy levels to your main Content folder

Debug Commands (Console):
- showlog - Show console output
- stat levels - Show level loading stats
- Enable verbose logging in Project Settings → Meta Login

11) Project Structure Integration

These classes form the foundation of the Meta Login plugin and work together to provide authentication, UI flow control, and basic session scaffolding.

How they fit together

• UI widgets WBP_LoginScreen and WBP_MainMenu call functions on UMetaGameInstance.
• UMetaGameInstance communicates with the Backend over HTTP and broadcasts events (login success/fail, token, logout).
• AMetaGameMode listens to these events, shows/hides the login and main menu, and transitions to levels (Lobby/Game).
• AMetaGameSession listens to GameInstance events, tracks active players, and enforces MaxConcurrentPlayers.
• AMetaGameState replicates simple server state and the leaderboard toggle.

Responsibilities

• UMetaGameInstance: Owns user/session state, talks to the backend, exposes easy BP functions (LoginUser, RegisterUser, LogoutUser, LoginAsGuest). Emits events you can bind to in Blueprints.
• AMetaGameMode: Shows/hides login and main menu widgets based on settings, and controls level transitions after login.
• AMetaGameSession: Listens to login/token events, maintains a simple active player list, enforces MaxConcurrentPlayers.
• AMetaGameState: Replicates lightweight server info and leaderboard flag; provides helper methods like SetServerMessage.
• UMetaLoginBlueprintLibrary: Small helpers to read settings and construct URLs.

Minimal integration steps

1) Set UMetaGameInstance and AMetaGameMode in Maps & Modes.
2) Assign your own WBP_LoginScreen and WBP_MainMenu in Project Settings → Meta Login.
3) In your login widget, call LoginUser(...) on click and bind to OnLoginSuccess/OnLoginFailed.
4) Optionally place a AMetaGameSession in your persistent level if you want player tracking; set MaxConcurrentPlayers in settings.
5) If you need a leaderboard flag or server message, use AMetaGameState helpers.

Notes

• MMO/Multiplayer methods are stubs. Replace or extend for a real backend/session solution.
• LoginAsGuest() works offline (no backend). Useful for fast testing of UI and level transitions.