Game mechanics, physics systems, combat, and interactive gameplay features.
Overview#
The Gameplay API provides endpoints for implementing core game mechanics including combat systems, physics simulation, inventory management, quest systems, and AI-driven NPC behavior.
Base Path: /v1/gameplay
Authentication: Bearer token required
Endpoints Summary#
| Method | Path | Description |
|---|---|---|
| POST | /combat/simulate |
Simulate combat encounter |
| POST | /combat/calculate-damage |
Calculate damage values |
| GET | /combat/stats/{characterId} |
Get combat statistics |
| POST | /physics/simulate |
Run physics simulation |
| POST | /physics/raycast |
Perform raycast query |
| POST | /physics/collision |
Check collision detection |
| POST | /inventory/create |
Create inventory system |
| POST | /inventory/{inventoryId}/add |
Add item to inventory |
| POST | /inventory/{inventoryId}/remove |
Remove item |
| POST | /inventory/{inventoryId}/transfer |
Transfer between inventories |
| POST | /quest/create |
Create quest |
| POST | /quest/{questId}/update |
Update quest progress |
| GET | /quest/{questId}/status |
Get quest status |
| POST | /dialogue/generate |
Generate dialogue options |
| POST | /dialogue/respond |
Process dialogue response |
| POST | /economy/transaction |
Process economic transaction |
| GET | /economy/balance |
Get currency balance |
| POST | /crafting/recipe |
Check crafting recipe |
| POST | /crafting/craft |
Craft item |
Combat System#
Simulate Combat#
Run a combat simulation between entities.
POST /v1/gameplay/combat/simulate
Authorization: Bearer <token>
Content-Type: application/json
{
"combatType": "turn_based",
"participants": [
{
"id": "player_001",
"team": "player",
"stats": {
"health": 100,
"attack": 25,
"defense": 15,
"speed": 20,
"critChance": 0.1,
"critMultiplier": 1.5
},
"abilities": ["slash", "shield_bash", "heal"],
"equipment": {
"weapon": "sword_iron",
"armor": "plate_steel"
}
},
{
"id": "enemy_goblin_01",
"team": "enemy",
"stats": {
"health": 50,
"attack": 15,
"defense": 5,
"speed": 25
},
"abilities": ["scratch", "dodge"],
"ai": "aggressive"
}
],
"rules": {
"turnOrder": "speed",
"maxTurns": 100,
"allowFleeing": true
},
"environment": {
"terrain": "dungeon",
"lighting": "dim",
"hazards": ["pit_trap"]
}
}
Combat Types:
| Type | Description |
|---|---|
turn_based |
Traditional turn-based combat |
real_time |
Real-time combat simulation |
action |
Action RPG style |
tactical |
Tactical grid-based |
auto_battle |
Automatic battle resolution |
Response:
{
"success": true,
"data": {
"result": "victory",
"winner": "player",
"turns": 8,
"duration": 45.5,
"combatLog": [
{
"turn": 1,
"actor": "enemy_goblin_01",
"action": "scratch",
"target": "player_001",
"damage": 12,
"effects": []
},
{
"turn": 1,
"actor": "player_001",
"action": "slash",
"target": "enemy_goblin_01",
"damage": 28,
"effects": ["bleeding"]
}
],
"finalState": {
"player_001": { "health": 76, "status": "alive" },
"enemy_goblin_01": { "health": 0, "status": "defeated" }
},
"rewards": {
"experience": 150,
"gold": 25,
"items": ["goblin_ear", "rusty_dagger"]
},
"statistics": {
"damageDealt": { "player_001": 128 },
"damageTaken": { "player_001": 24 },
"criticalHits": 2,
"abilitiesUsed": 5
}
}
}
Calculate Damage#
Calculate damage for an attack.
POST /v1/gameplay/combat/calculate-damage
Authorization: Bearer <token>
Content-Type: application/json
{
"attacker": {
"attack": 50,
"weaponDamage": { "min": 10, "max": 20 },
"critChance": 0.15,
"critMultiplier": 2.0,
"bonuses": [
{ "type": "elemental", "element": "fire", "value": 10 }
]
},
"defender": {
"defense": 20,
"armor": 15,
"resistances": { "fire": 0.25, "ice": -0.1 },
"vulnerabilities": []
},
"attackType": "physical",
"element": "fire",
"isCritical": false,
"modifiers": ["backstab", "weakened"]
}
Response:
{
"success": true,
"data": {
"baseDamage": 45,
"elementalDamage": 7,
"totalDamage": 52,
"mitigated": 18,
"finalDamage": 34,
"breakdown": {
"weaponRoll": 15,
"attackBonus": 30,
"elementalBonus": 7,
"defenseReduction": -15,
"armorReduction": -8,
"resistanceReduction": -3,
"modifierBonus": 8
},
"effects": ["burning"],
"isCritical": false,
"isBlocked": false,
"isDodged": false
}
}
Physics System#
Simulate Physics#
Run physics simulation on objects.
POST /v1/gameplay/physics/simulate
Authorization: Bearer <token>
Content-Type: application/json
{
"objects": [
{
"id": "ball_001",
"type": "sphere",
"position": [0, 10, 0],
"velocity": [5, 0, 0],
"mass": 1.0,
"radius": 0.5,
"material": "rubber",
"restitution": 0.8,
"friction": 0.3
},
{
"id": "ground",
"type": "plane",
"position": [0, 0, 0],
"normal": [0, 1, 0],
"static": true,
"material": "concrete"
}
],
"forces": [
{ "type": "gravity", "value": [0, -9.81, 0] },
{ "type": "wind", "value": [2, 0, 1] }
],
"duration": 5.0,
"timeStep": 0.016,
"substeps": 4
}
Response:
{
"success": true,
"data": {
"frames": [
{
"time": 0.0,
"objects": {
"ball_001": {
"position": [0, 10, 0],
"velocity": [5, 0, 0],
"rotation": [0, 0, 0, 1]
}
}
},
{
"time": 0.016,
"objects": {
"ball_001": {
"position": [0.08, 9.998, 0],
"velocity": [5, -0.157, 0],
"rotation": [0, 0, 0, 1]
}
}
}
],
"collisions": [
{
"time": 1.43,
"objectA": "ball_001",
"objectB": "ground",
"point": [7.15, 0.5, 0],
"normal": [0, 1, 0],
"impulse": 12.5
}
],
"statistics": {
"totalFrames": 313,
"collisionCount": 3,
"maxVelocity": 14.2
}
}
}
Raycast Query#
Perform a raycast for collision detection.
POST /v1/gameplay/physics/raycast
Authorization: Bearer <token>
Content-Type: application/json
{
"origin": [0, 1.5, 0],
"direction": [1, 0, 0],
"maxDistance": 100,
"layers": ["characters", "props", "terrain"],
"excludeIds": ["player_001"],
"mode": "all"
}
Response:
{
"success": true,
"data": {
"hits": [
{
"objectId": "wall_001",
"point": [5.2, 1.5, 0],
"normal": [-1, 0, 0],
"distance": 5.2,
"layer": "terrain"
},
{
"objectId": "enemy_001",
"point": [3.1, 1.5, 0],
"normal": [-1, 0, 0],
"distance": 3.1,
"layer": "characters"
}
],
"count": 2
}
}
Inventory System#
Create Inventory#
Create a new inventory instance.
POST /v1/gameplay/inventory/create
Authorization: Bearer <token>
Content-Type: application/json
{
"ownerId": "player_001",
"ownerType": "character",
"type": "backpack",
"capacity": {
"slots": 30,
"maxWeight": 100
},
"restrictions": {
"allowedCategories": ["weapon", "armor", "consumable", "material"],
"forbiddenItems": ["quest_key_special"]
},
"stackingRules": {
"consumable": 99,
"material": 999,
"default": 1
}
}
Add Item#
Add an item to inventory.
POST /v1/gameplay/inventory/{inventoryId}/add
Authorization: Bearer <token>
Content-Type: application/json
{
"itemId": "potion_health_large",
"quantity": 5,
"slot": null,
"metadata": {
"quality": "legendary",
"enchantments": ["life_steal"]
}
}
Response:
{
"success": true,
"data": {
"added": true,
"slot": 12,
"stackId": "stack_abc123",
"newQuantity": 5,
"remainingCapacity": {
"slots": 17,
"weight": 95.5
}
}
}
Transfer Items#
Transfer items between inventories.
POST /v1/gameplay/inventory/{inventoryId}/transfer
Authorization: Bearer <token>
Content-Type: application/json
{
"targetInventoryId": "inv_chest_001",
"items": [
{ "slot": 5, "quantity": 10 },
{ "slot": 12, "quantity": "all" }
],
"validateCapacity": true
}
Quest System#
Create Quest#
Define a new quest.
POST /v1/gameplay/quest/create
Authorization: Bearer <token>
Content-Type: application/json
{
"id": "quest_dragon_slayer",
"name": "The Dragon's Bane",
"description": "Defeat the ancient dragon terrorizing the village",
"type": "main",
"level": 25,
"objectives": [
{
"id": "obj_gather_info",
"type": "talk",
"description": "Speak with the village elder",
"target": "npc_elder",
"required": true
},
{
"id": "obj_find_lair",
"type": "discover",
"description": "Find the dragon's lair",
"target": "location_dragon_lair",
"required": true,
"dependsOn": ["obj_gather_info"]
},
{
"id": "obj_slay_dragon",
"type": "kill",
"description": "Defeat the Ancient Dragon",
"target": "creature_ancient_dragon",
"count": 1,
"required": true,
"dependsOn": ["obj_find_lair"]
},
{
"id": "obj_rescue_prisoners",
"type": "rescue",
"description": "Rescue captured villagers",
"target": "villager",
"count": 5,
"required": false
}
],
"rewards": {
"experience": 5000,
"gold": 1000,
"items": ["sword_dragonbane", "dragon_scale_armor"],
"reputation": { "village": 100, "kingdom": 50 }
},
"prerequisites": {
"level": 20,
"quests": ["quest_village_defender"],
"reputation": { "village": 50 }
},
"timeLimit": null,
"repeatable": false
}
Update Quest Progress#
Update objective progress.
POST /v1/gameplay/quest/{questId}/update
Authorization: Bearer <token>
Content-Type: application/json
{
"playerId": "player_001",
"objectiveId": "obj_rescue_prisoners",
"action": "increment",
"value": 2,
"metadata": {
"location": "dragon_lair_prison",
"method": "stealth"
}
}
Response:
{
"success": true,
"data": {
"questId": "quest_dragon_slayer",
"status": "in_progress",
"objectives": {
"obj_gather_info": { "status": "completed", "progress": 1, "target": 1 },
"obj_find_lair": { "status": "completed", "progress": 1, "target": 1 },
"obj_slay_dragon": {
"status": "in_progress",
"progress": 0,
"target": 1
},
"obj_rescue_prisoners": {
"status": "in_progress",
"progress": 3,
"target": 5
}
},
"completionPercentage": 60,
"unlockedObjectives": ["obj_slay_dragon"],
"events": [
{
"type": "objective_progress",
"objective": "obj_rescue_prisoners",
"progress": 3
}
]
}
}
Dialogue System#
Generate Dialogue#
Generate contextual dialogue options.
POST /v1/gameplay/dialogue/generate
Authorization: Bearer <token>
Content-Type: application/json
{
"npcId": "npc_merchant",
"playerId": "player_001",
"context": {
"location": "market_square",
"timeOfDay": "afternoon",
"weather": "sunny",
"playerReputation": 75,
"previousInteractions": 5,
"activeQuests": ["quest_find_artifact"],
"playerInventory": ["gold:500", "rare_gem"],
"npcMood": "friendly"
},
"conversationHistory": [
{ "speaker": "npc", "text": "Welcome back, friend! Looking for anything special today?" }
],
"style": "medieval_fantasy",
"maxOptions": 4
}
Response:
{
"success": true,
"data": {
"options": [
{
"id": "opt_1",
"text": "I'm looking for information about the ancient artifact.",
"tone": "inquisitive",
"skillCheck": null,
"consequences": { "questProgress": true }
},
{
"id": "opt_2",
"text": "Show me your finest wares, merchant.",
"tone": "neutral",
"skillCheck": null,
"consequences": { "opensShop": true }
},
{
"id": "opt_3",
"text": "[Persuade] Perhaps you could offer me a discount, given our history?",
"tone": "persuasive",
"skillCheck": { "skill": "persuasion", "difficulty": 15 },
"consequences": { "discount": 0.15 }
},
{
"id": "opt_4",
"text": "I'll be on my way. Farewell.",
"tone": "farewell",
"skillCheck": null,
"consequences": { "endsConversation": true }
}
],
"npcState": {
"mood": "friendly",
"disposition": 75,
"knowsAboutArtifact": true
}
}
}
Economy System#
Process Transaction#
Execute an economic transaction.
POST /v1/gameplay/economy/transaction
Authorization: Bearer <token>
Content-Type: application/json
{
"type": "purchase",
"buyerId": "player_001",
"sellerId": "npc_merchant",
"items": [
{ "itemId": "potion_health", "quantity": 10, "pricePerUnit": 25 },
{ "itemId": "sword_steel", "quantity": 1, "pricePerUnit": 500 }
],
"currency": "gold",
"applyDiscounts": true,
"validateFunds": true
}
Response:
{
"success": true,
"data": {
"transactionId": "txn_abc123",
"status": "completed",
"subtotal": 750,
"discounts": [
{ "type": "reputation", "amount": 75, "reason": "Loyal customer" }
],
"taxes": 0,
"total": 675,
"buyerBalance": { "before": 1000, "after": 325 },
"sellerBalance": { "before": 5000, "after": 5675 },
"itemsTransferred": [
{ "itemId": "potion_health", "quantity": 10 },
{ "itemId": "sword_steel", "quantity": 1 }
]
}
}
Crafting System#
Check Recipe#
Verify crafting recipe requirements.
POST /v1/gameplay/crafting/recipe
Authorization: Bearer <token>
Content-Type: application/json
{
"recipeId": "recipe_sword_enchanted",
"crafterId": "player_001",
"checkInventory": true
}
Response:
{
"success": true,
"data": {
"recipeId": "recipe_sword_enchanted",
"name": "Enchanted Steel Sword",
"canCraft": true,
"requirements": {
"level": { "required": 15, "current": 20, "met": true },
"skill": { "required": 50, "current": 65, "met": true },
"materials": [
{ "itemId": "steel_ingot", "required": 3, "available": 5, "met": true },
{
"itemId": "magic_essence",
"required": 1,
"available": 2,
"met": true
},
{ "itemId": "leather_grip", "required": 1, "available": 1, "met": true }
],
"tools": [
{ "toolId": "forge", "available": true },
{ "toolId": "enchanting_table", "available": true }
]
},
"output": {
"itemId": "sword_enchanted_steel",
"quantity": 1,
"quality": "rare"
},
"craftingTime": 30,
"experienceGain": 150
}
}
Craft Item#
Execute crafting.
POST /v1/gameplay/crafting/craft
Authorization: Bearer <token>
Content-Type: application/json
{
"recipeId": "recipe_sword_enchanted",
"crafterId": "player_001",
"quantity": 1,
"qualityBonus": true
}
Error Codes#
| Code | Description |
|---|---|
INVALID_COMBAT_CONFIG |
Combat configuration is invalid |
INSUFFICIENT_FUNDS |
Not enough currency |
INVENTORY_FULL |
No inventory space available |
QUEST_NOT_FOUND |
Quest ID does not exist |
OBJECTIVE_LOCKED |
Objective prerequisites not met |
RECIPE_REQUIREMENTS_NOT_MET |
Missing materials or skills |
PHYSICS_TIMEOUT |
Simulation took too long |
INVALID_ITEM |
Item ID does not exist |
Rate Limits#
| Endpoint | Limit |
|---|---|
| Combat simulation | 10/minute |
| Physics simulation | 20/minute |
| Inventory operations | 100/minute |
| Quest updates | 50/minute |
| Dialogue generation | 30/minute |
| Transactions | 50/minute |