Skip to Content
Loremind Unity SDKBackend Setup

Backend Setup

Before shipping your game, you must route NPC requests through your backend. This page explains why and how to configure the SDK.

Why You Need a Backend

During development, the SDK calls LoreMind directly using your Server API Key stored in EditorPrefs. This is convenient for prototyping but not safe for production.

The Problem with Direct Calls

If you ship a game that calls LoreMind directly:

  1. Your API key is in the build - Anyone can extract it
  2. No player identification - Can’t use long-term memory
  3. No custom rate limiting - Can’t control per-player usage
  4. No audit trail - Can’t track who’s making requests

The Backend Pattern

Instead, your game calls your backend, and your backend calls LoreMind:

┌─────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Your Game  │ --> │  Your Backend   │ --> │  LoreMind API   │
│  (Client)   │     │  (adds API key) │     │                 │
└─────────────┘     └─────────────────┘     └─────────────────┘

Your backend:

  1. Authenticates players - Using Steam, Epic, PlayFab, or custom auth
  2. Adds the API key - Stored securely in environment variables
  3. Adds player ID - Enables long-term memory
  4. Forwards to LoreMind - And returns responses to your game

Before You Start

You need:

  1. A working NPC in the Editor - Complete Installation and Your First NPC first
  2. A game backend - PlayFab, Firebase, Nakama, or custom server
  3. Backend code that calls LoreMind - See Server Integration for examples

Configuring the SDK

Step 1: Set Up Your Backend Endpoint

Your backend needs an endpoint that:

  1. Receives NPC requests from your game
  2. Authenticates the player
  3. Adds your LoreMind API key
  4. Forwards to https://loremind.peekgames.dev/api/loremind/v1/npc/interact
  5. Returns the response

See Server Integration for complete backend examples (PlayFab, Firebase, Nakama, Node.js, .NET).

Step 2: Configure the SDK

  1. Open Window > LoreMind > Control Panel
  2. Set Transport Mode to Custom Backend
  3. Enter your Backend URL (e.g., https://api.yourgame.com/api/npc/interact)
  4. Click Save

The SDK will now route all NPC requests to your backend instead of calling LoreMind directly.

Step 3: Test in a Build

  1. Create a development build
  2. Run it and test NPC interactions
  3. Verify requests go through your backend (check server logs)
  4. Verify responses work correctly

What Your Backend Receives

The SDK sends this JSON to your backend:

{
  "text": "Hello, what's your name?",
  "entityMindId": "em_innkeeper_garrick",
  "context": {
    "location": "The Rusty Anvil Tavern",
    "timeOfDay": "evening",
    "nearbyCharacters": ["Mysterious stranger"]
  },
  "memory": {
    "retrieve": true
  }
}

Your backend should:

  1. Authenticate the player using your auth system
  2. Add playerId from your auth (e.g., Steam ID, account ID)
  3. Add Authorization: Bearer YOUR_API_KEY header
  4. Forward to LoreMind
  5. Return the response to the game

Programmatic Configuration

You can also configure the transport in code:

using Peek.LoreMind;
 
// Set the backend URL programmatically
var transport = new CustomBackendTransport(
    backendUrl: "https://api.yourgame.com/api/npc/interact"
);
npc.SetTransport(transport);

This is useful if you need different backends for different environments (dev, staging, production).

Long-Term Memory

Memory requires playerId to identify players. Your backend provides this:

// Your backend adds this before forwarding to LoreMind
{
  "text": "Hello!",
  "entityMindId": "em_innkeeper",
  "playerId": "steam_76561198012345678",  // Your backend adds this
  "memory": { "retrieve": true }
}

Good player ID choices:

  • Platform IDs: steam_76561198012345678, epic_abc123
  • Game account IDs: account_12345
  • Persistent UUIDs: 550e8400-e29b-41d4-a716-446655440000

Avoid:

  • Temporary session IDs (memories won’t persist)
  • Email addresses (PII concerns)
  • Device IDs (players switch devices)

See Long-Term Memory for details.

Testing Checklist

Before shipping, verify:

  • API key is stored in backend environment variables (not in code)
  • API key is NOT in your game build
  • Player authentication works correctly
  • Requests include playerId
  • Error responses are handled gracefully
  • Rate limits reviewed in Dashboard
  • Long-term memory works (if using)

Troubleshooting

”Unauthorized” errors from LoreMind

  • Check your API key is correct (starts with sk_server_)
  • Verify the key is in the Authorization header
  • Make sure you’re using a Server Key, not an Editor Key

”Entity Mind not found”

  • Verify the entityMindId exists in your dashboard
  • Check for typos in the ID

Requests not reaching your backend

  • Check the backend URL is correct in Control Panel
  • Verify your backend is running and accessible
  • Check for CORS issues if testing in browser

Memory not working

  • Ensure playerId is included in requests
  • Use consistent player IDs across sessions
  • Verify memory: { retrieve: true } is included

Security Best Practices

Never Expose Your API Key

  • Store it in environment variables on your backend
  • Never commit it to version control
  • Never include it in game builds

Validate Requests

  • Authenticate players before forwarding requests
  • Consider validating entityMindId against a whitelist

Use HTTPS

  • LoreMind API requires HTTPS
  • Your backend should require HTTPS too

Monitor Usage

  • Set up billing alerts in the dashboard
  • Review rate limits in Dashboard → Project Settings
  • Track per-player usage if needed

Next Steps

Last updated on
Voice OutputAPI Reference