taskforge

Lightweight C++ toolkit for robot manipulation simulation with a fixed task UI and swappable robot/training backends.

This project is a small open-source sandbox for kinematics-driven manipulation tasks. The environment and dashboard stay fixed. What you can swap is:

• robot kinematics implementation
• robot model parameters
• training algorithm

The current application is built around a single manipulation task family and a single dashboard, which intentionally define the compatibility constraints for robots and trainers.

What It Is

• lightweight C++ manipulation simulation toolkit
• fixed pick-lift-place environment with a live task-centric dashboard
• pluggable robot kinematics through a task-specific robot contract
• pluggable training algorithms through a shared trainer interface

What It Is Not

• not a general robotics simulator
• not a high-fidelity physics engine
• not a generic framework for arbitrary environments and arbitrary UIs
• not plug-and-play for robots that do not match the manipulation task contract

Current Architecture

The app keeps two things fixed:

• one manipulation environment: PickAndLiftEnv
• one visualization layer: TrainingDashboard

It allows swapping:

• ManipulationKinematics implementations
• ITrainer implementations

That means the environment and dashboard impose constraints on the robot and algorithm, rather than the other way around.

Core Contracts

Robot Contract

ManipulationKinematics extends the base kinematics contract and defines what the fixed environment needs from a compatible robot:

• jointCount()
• homeJointState()
• forwardKinematics(...)
• jointActionScales()
• jointLimits()
• workspaceRadius()
• gripperActionDimension()

The current reference implementation is ScaraKinematics.

Environment Contract

Environment exposes:

• reset()
• step(action)
• state_dim()
• action_dim()
• action_limit()

The current environment is PickAndLiftEnv, implementing a pick-lift-place task with:

• randomized object sampling
• randomized place target sampling
• grasp / lift / place reward shaping
• task render state for the dashboard

Trainer Contract

ITrainer is the shared application-facing trainer interface:

• trainStep(...)
• metrics()

The dashboard consumes TrainerMetrics, not a concrete trainer class. The current reference trainer is SACTrainer.

Current Example

The default composed app is:

• robot: ScaraKinematics
• environment: PickAndLiftEnv
• trainer: SACTrainer
• UI: TrainingDashboard

Application composition is handled in code through:

• buildRobot(...)
• buildTrainer(...)
• buildTrainingApp(...)

This is implemented in:

• lib/app/training_app.hpp
• src/app/training_app.cpp

Plug-and-Play Boundaries

New robot

A new robot can be plugged in if it implements ManipulationKinematics and satisfies the task assumptions:

• one TCP
• one gripper action channel
• meaningful workspace radius
• valid joint limits and action scales

If it does not, PickAndLiftEnv should reject it early with a clear error.

New training algorithm

A new algorithm can be plugged in if it implements ITrainer and provides TrainerMetrics compatible with the dashboard.

The dashboard expects:

• progress metrics
• episode reward metrics
• success / truncation rates
• reward history
• three labeled scalar series for optimization metrics

That means a non-SAC trainer can still work, but it must expose metrics through the same dashboard-facing contract.

Repository Structure

lib/
  app/        # application composition
  env/        # environment interface and fixed manipulation env
  rl/         # trainer interface, metrics, SAC implementation
  robotics/   # robot and task-specific kinematics contracts
  ui/         # fixed dashboard and render state

src/
  app/
  env/
  rl/
  robotics/
  ui/

main.cpp

Dependencies

• C++20
• CMake 3.20+
• Eigen3
• raylib
• LibTorch

LibTorch is required locally, but it should not be committed to the repository.

The default expected path is:

third_party/libtorch

Recommended setup is a local symlink:

make link-libtorch LIBTORCH_ROOT=/abs/path/to/libtorch

Alternative setup options:

cmake -S . -B build -DTASKFORGE_LIBTORCH_ROOT=/abs/path/to/libtorch

export LIBTORCH_ROOT=/abs/path/to/libtorch
cmake -S . -B build

Backward compatibility note: SCARA_LIBTORCH_ROOT is still accepted, but deprecated.

Build

cmake -S . -B build
cmake --build build

Or:

make build

If LibTorch is missing, CMake now fails with an explicit message instead of a generic find_package(Torch) error.

API Docs

Doxygen configuration is included in the repo.

Generate HTML docs with:

make docs

Or generate and open them directly on macOS:

make docs-open

The easiest entrypoint is:

docs/index.html

Notes:

• this requires a local doxygen installation
• Graphviz dot is optional; the checked-in configuration does not require it
• the docs focus on the public API in lib/
• generated HTML lives in docs/api/
• the Doxygen docs are grouped by module: app, robotics, env, rl, ui
• the easiest browsing path is docs/index.html -> Topics

Run

./build/taskforge

Or:

make run

Why This Exists

This project is for cases where full robotics learning stacks are too heavy for quick iteration.

It is intended to support:

• rapid prototyping of manipulation task logic
• swapping robot embodiments under one fixed task
• comparing trainers under one fixed UI
• debugging reward shaping and observation design in C++

Current Limitations

• the environment is fixed to a specific manipulation task family
• the dashboard is fixed and expects shared trainer metrics
• robots must satisfy the task-specific manipulation contract
• no config-driven composition yet; composition is code-based for now

Short Description

Fixed manipulation environment and dashboard, with swappable robot kinematics and training algorithms.