Developer Mode Endpoints

Admin-only REST API endpoints for in-game visual editing and object management.

Base URL

All endpoints are under: /wp-json/orbemorder/v1/

Authentication

All Developer Mode endpoints require manage_options capability (Administrator role).

Object Positioning

POST /set-item-position/

Update object position coordinates.

Method: POST
Permission: Administrator

Request:

{
  "id": 123,              // Post ID
  "top": 2500,            // Y coordinate
  "left": 3000,           // X coordinate
  "meta": "",             // Optional: meta key for trigger positioning
  "walkingPath": "false"  // "true" for path recording
}

Response:

{
  "success": true,
  "data": "success"
}

Use Cases:

Path Recording: When walkingPath is set to "true", coordinates are added to the object's explore-path meta array instead of replacing position.

Object Sizing (Pro feature)

POST /set-item-size/

Update object dimensions.

Method: POST
Permission: Administrator

Request:

{
  "id": 123,      // Post ID
  "height": 100,  // Height in pixels
  "width": 80,    // Width in pixels
  "meta": ""      // Optional: meta key for trigger sizing
}

Response:

{
  "success": true,
  "data": "success"
}

Use Cases:

Dynamic Field Loading (Pro feature)

POST /get-new-fields/

Retrieve configuration fields for a post type.

Method: POST
Permission: Administrator

Request:

{
  "type": "explore-character"
}

Response:

{
  "success": true,
  "data": "<form fields HTML>"
}

Returns: HTML form fields for the specified post type's meta box.

Use Cases:

Supported Types:

Object Creation

POST /add-new/ (Pro feature)

Create a new game object from Developer Mode.

Method: POST
Permission: Administrator

Request:

{
  "type": "explore-character",
  "area": "level-1",
  "values": {
    "title": "New NPC",
    "featured-image": "https://...",
    "explore-top": 2500,
    "explore-left": 3000,
    "explore-height": 100,
    "explore-width": 80,
    // ... other meta fields
  }
}

Response:

{
  "success": true,
  "data": 456  // New post ID
}

Validation:

Created Post:

Security Considerations

Permission Checks

All endpoints verify manage_options capability:

$permission_callback = function () {
    return current_user_can('manage_options');
};

Meta Key Validation

Only meta keys starting with explore- can be modified:

if (!str_starts_with($meta, 'explore-')) {
    return error_response('Invalid meta key');
}

Post Type Validation

Only explore-* post types can be created:

if (!str_starts_with($post_type, 'explore-')) {
    return error_response('Invalid post type');
}

Post Access

Endpoints verify user can edit the specified post:

if (!current_user_can('edit_post', $post_id)) {
    return error_response('Invalid item ID');
}

Usage in Developer Mode

Position Update Flow

sequenceDiagram
    participant UI as Dev Mode UI
    participant API as REST API
    participant DB as Database

    UI->>UI: User drags object
    UI->>API: POST /set-item-position/
    API->>DB: Update post meta
    DB->>API: Confirm
    API->>UI: Success response
    UI->>UI: Visual confirmation

Object Creation Flow

sequenceDiagram
    participant UI as Dev Mode UI
    participant Fields as Field Loader
    participant API as REST API
    participant DB as Database

    UI->>Fields: POST /get-new-fields/
    Fields->>UI: Return form HTML
    UI->>UI: User fills form
    UI->>API: POST /add-new/
    API->>DB: Create post
    DB->>API: Return post ID
    API->>UI: Success + ID
    UI->>UI: Display new object

Error Responses

Common Errors

Not Authenticated:

{
  "success": false,
  "data": "User not authenticated"
}

Invalid Post Type:

{
  "success": false,
  "data": "Invalid post type"
}

Invalid Meta Key:

{
  "success": false,
  "data": "Invalid meta key"
}

Invalid Post ID:

{
  "success": false,
  "data": "Invalid item ID"
}

Missing Data:

{
  "success": false,
  "data": "Invalid data point"
}

Post Creation Failed:

{
  "success": false,
  "data": "Post creation failed."
}

Example Usage

Update Object Position

async function updatePosition(postId, top, left) {
  const response = await fetch('/wp-json/orbemorder/v1/set-item-position/', {
    method: 'POST',
    headers: {
      'X-WP-Nonce': OrbemOrder.orbemNonce,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      id: postId,
      top: top,
      left: left
    })
  });

  return await response.json();
}

Create New Character

async function createCharacter(characterData) {
  const response = await fetch('/wp-json/orbemorder/v1/add-new/', {
    method: 'POST',
    headers: {
      'X-WP-Nonce': OrbemOrder.orbemNonce,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'explore-character',
      area: 'current-area',
      values: characterData
    })
  });

  return await response.json();
}