luckyrobots 0.1.64

Robotics-AI Training in Hyperrealistic Game Environments

Infinite synthetic data generation for embodied AI

https://github.com/user-attachments/assets/0ab2953d-b188-4af7-a225-71decdd2378c

Lucky Robots

Hyperrealistic robotics simulation framework with Python API for embodied AI training and testing.

Quick Start

1. Download Lucky World Executable from our releases page and add its path to your system variables

   # Set environment variables (choose one method):
   
   # Method 1: Set LUCKYWORLD_PATH directly to the executable
   export LUCKYWORLD_PATH=/path/to/LuckyWorld.exe  # Windows
   export LUCKYWORLD_PATH=/path/to/LuckyWorld      # Linux/Mac
   
   # Method 2: Set LUCKYWORLD_HOME to the directory containing the executable
   export LUCKYWORLD_HOME=/path/to/luckyworld/directory
   

2. Create conda environment (recommended)

   conda create -n luckyrobots python
   conda activate luckyrobots
   

3. Install

   pip install luckyrobots
   

4. Run Example

   git clone https://github.com/luckyrobots/luckyrobots.git
   cd luckyrobots/examples
   python controller.py
   

Basic Usage

from luckyrobots import LuckyRobots, Node
import numpy as np

# Create controller node
class RobotController(Node):
    async def control_loop(self):
        # Reset environment
        reset_response = await self.reset_client.call(Reset.Request())

        # Send actions
        actuator_values = np.array([0.1, 0.2, -0.1, 0.0, 0.5, 1.0])
        step_response = await self.step_client.call(Step.Request(actuator_values=actuator_values))

        # Access observations
        observation = step_response.observation
        joint_states = observation.observation_state
        camera_data = observation.observation_cameras

# Start simulation
luckyrobots = LuckyRobots()
controller = RobotController()
luckyrobots.register_node(controller)
luckyrobots.start(scene="kitchen", robot="so100", task="pickandplace")

Available Robots & Environments

Robots

• so100: 6-DOF manipulator with gripper
• stretch_v1: Mobile manipulator
• dji300: Quadcopter drone

Scenes

• kitchen: Residential kitchen environment
• loft: Open floor plan apartment
• drone_flight: Outdoor flight area

Tasks

• pickandplace: Object manipulation
• navigation: Path planning and movement

API Reference

Core Classes

LuckyRobots: Main simulation manager

• start(scene, robot, task, observation_type): Initialize simulation
• register_node(node): Add controller node
• spin(): Run main loop

Node: Base class for robot controllers

• create_client(service_type, service_name): Create service client
• create_service(service_type, service_name, handler): Create service server

Services

Reset: Reset robot to initial state

request = Reset.Request(seed=42, options={})
response = await reset_client.call(request)

Step: Send action and get observation

request = Step.Request(actuator_values=[0.1, 0.2, -0.1])
response = await step_client.call(request)

Observations

Access sensor data from step responses:

# Joint positions and velocities
joint_states = response.observation.observation_state

# Camera images (RGB + depth)
for camera in response.observation.observation_cameras:
    image = camera.image_data  # numpy array
    name = camera.camera_name  # "head_cam", "hand_cam", etc.

Command Line Interface

# Basic usage
python controller.py --robot so100 --scene kitchen --task pickandplace

# With camera display
python controller.py --show-camera --rate 30

# Custom host/port
python controller.py --host 192.168.1.100 --port 3001

Configuration

Robot configurations are defined in src/luckyrobots/config/robots.yaml:

so100:
  action_space:
    actuator_names: [shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper]
    actuator_limits:
      - name: shoulder_pan
        lower: -2.2
        upper: 2.2
  available_scenes: [kitchen]
  available_tasks: [pickandplace]

Architecture

Lucky Robots uses a distributed node architecture:

• Manager Node: Central message routing
• LuckyRobots Node: Simulation interface
• Controller Nodes: User-defined robot controllers
• WebSocket Transport: Inter-node communication
• Lucky World: Physics simulation backend

Development

Setup Development Environment

git clone https://github.com/luckyrobots/luckyrobots.git
cd luckyrobots
pip install -e .

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes and add tests
4. Submit a pull request

License

MIT License - see LICENSE file.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: Community Server