Skip to content

Getting Started

This guide will help you submit your first policy to BotManifold in under 5 minutes.

Prerequisites

  • Python 3.9 or higher
  • pip package manager
  • A text editor

Step 1: Install the SDK

pip install botmanifold

Step 2: Create Your Policy

Create a file called policy.py:

import numpy as np

def policy(observation: dict) -> np.ndarray:
    """
    Your robot control policy.

    Args:
        observation: Dictionary containing:
            - robot_state: Current robot joint positions/velocities
            - object_positions: XYZ positions of objects in the scene
            - target_positions: Where objects should be placed

    Returns:
        action: 7D numpy array [x, y, z, roll, pitch, yaw, gripper]
            - x, y, z: End-effector velocity (-1 to 1)
            - roll, pitch, yaw: Rotation velocity (-1 to 1)
            - gripper: Gripper command (-1 = close, 1 = open)
    """
    # Get robot position
    robot_pos = observation['robot_state'][:3]

    # Get object positions
    objects = observation['object_positions']

    if len(objects) == 0:
        # No objects, stay still
        return np.zeros(7)

    # Find the nearest object
    distances = [np.linalg.norm(robot_pos - obj) for obj in objects]
    nearest_idx = np.argmin(distances)
    target = objects[nearest_idx]

    # Calculate direction to target
    direction = target - robot_pos
    distance = np.linalg.norm(direction)

    if distance > 0.01:
        direction = direction / distance

    # Create action
    action = np.zeros(7)
    action[:3] = direction * 0.5  # Move toward target
    action[6] = 1.0 if distance > 0.05 else -1.0  # Open gripper if far, close if near

    return action

Step 3: Package Your Policy

Create a zip file containing your policy:

zip policy.zip policy.py

Multiple Files

If your policy uses multiple files or dependencies, include them all in the zip. The entry point must be policy.py with a policy() function.

Step 4: Submit

  1. Go to botmanifold.com/arena/submit
  2. Select a scenario (e.g., "Messy Room Challenge")
  3. Drag and drop your policy.zip
  4. Click "Submit Policy"

Option B: SDK

from botmanifold import BotManifoldClient

client = BotManifoldClient()

# Submit your policy
submission = client.submit(
    policy_path="policy.zip",
    scenario="messy_room_v1"
)

print(f"Submission ID: {submission.id}")
print(f"Status: {submission.status}")

Option C: REST API

curl -X POST https://botmanifold.com/api/submissions \
  -F "policy=@policy.zip" \
  -F "scenario_id=messy_room_v1"

Step 5: Watch the Results

After submission, your policy enters a queue:

  1. Queued: Waiting for a simulation worker
  2. Running: Simulation in progress
  3. Judging: AI evaluates the result
  4. Completed: Results available

View your submission at: 

https://botmanifold.com/arena/submissions/{submission_id}

You'll see:

  • Video: Recording of your robot performing the task
  • Verdict: PASS, FAIL, or PARTIAL
  • Score: Numerical performance metric
  • Judge Feedback: Explanation of the evaluation

Next Steps

Troubleshooting

"Policy function not found"

Ensure your zip file contains policy.py with a function named policy:

def policy(observation: dict) -> np.ndarray:
    ...

"Import error"

Only standard library and numpy are available. If you need other dependencies, include them in your zip file.

"Timeout"

Policies have a time limit per step (typically 100ms). Optimize your code or simplify your approach.

Need help? Check the FAQ or open an issue.