Skip to content

DexForce/EmbodiChain / .agents/skills/add-functor

add-functor

Verified

Use when adding a new observation, event, reward, action, dataset, or randomization functor to an EmbodiChain environment

Add Functor

Scaffold a new functor following EmbodiChain's Functor/FunctorCfg pattern.

When to Use

  • User asks to add an observation term, reward function, event handler, action term, dataset functor, or randomizer
  • User says "add a reward", "new observation", "create a randomizer", "add event functor"
  • Any new function needs to be registered in a manager config

Determine Functor Type

Functor TypeConfig ClassModule FileManagerSignature
ObservationObservationCfg (extends FunctorCfg)managers/observations/ObservationManager(env, obs, entity_cfg, ...) -> Tensor
ConditionConditionCfgmanagers/conditions.pyTerminationManager(env, ...) -> ConditionResult
RewardRewardCfg (extends FunctorCfg)managers/rewards.pyRewardManager(env, obs, action, info, ...) -> Tensor
EventEventCfg (extends FunctorCfg)managers/events.pyEventManager(env, env_ids, ...) -> None
ActionActionTermCfg (extends FunctorCfg)managers/actions.pyActionManagerVaries
DatasetDatasetFunctorCfg (extends FunctorCfg)managers/datasets.pyDatasetManager(env, ...) -> dict
RandomizationEventCfg (randomizations ARE events)managers/randomization/<type>.pyEventManager(env, env_ids, entity_cfg, ...) -> None

Two Functor Styles

Function-style (Preferred for Simple Functors)

A plain function with the right signature. Registered via FunctorCfg(func=my_function, params={...}).

def my_reward(
    env: EmbodiedEnv,
    obs: dict,
    action: EnvAction,
    info: dict,
    my_param: float = 1.0,       # params become keyword args
) -> torch.Tensor:
    """Short one-line summary.

    Longer description if needed.

    Args:
        env: The environment instance.
        obs: The observation dictionary.
        action: The action taken.
        info: The info dictionary.
        my_param: Description of this parameter.

    Returns:
        Reward tensor of shape (num_envs,).
    """
    # implementation
    return result

Class-style (Required When Functor Has State)

A class inheriting Functor, with __init__(cfg, env) and __call__(env, ...). Registered via FunctorCfg(func=MyClass, params={...}).

class my_randomizer(Functor):
    """One-line summary."""

    def __init__(self, cfg: FunctorCfg, env: EmbodiedEnv):
        super().__init__(cfg, env)
        # Extract params and initialize state
        self.entity_cfg: SceneEntityCfg = cfg.params["entity_cfg"]

    def __call__(self, env: EmbodiedEnv, env_ids: torch.Tensor, **kwargs):
        """Apply the randomization.

        Args:
            env: The environment instance.
            env_ids: Target environment IDs.
        """
        # implementation

Steps

1. Identify Functor Type and Style

Ask the user:

  1. Which manager? (observation / reward / event / action / dataset / randomization)
  2. Function or class style? (function for stateless, class for stateful)
  3. What does it do? (brief description for naming + docstring)

2. Choose the Right Module File

Place the functor in the existing module for its type:

TypeFile
Observationembodichain/lab/gym/envs/managers/observations/
Rewardembodichain/lab/gym/envs/managers/rewards.py
Eventembodichain/lab/gym/envs/managers/events.py
Actionembodichain/lab/gym/envs/managers/actions.py
Datasetembodichain/lab/gym/envs/managers/datasets.py
Physics randomizationembodichain/lab/gym/envs/managers/randomization/physics.py
Visual randomizationembodichain/lab/gym/envs/managers/randomization/visual.py
Spatial randomizationembodichain/lab/gym/envs/managers/randomization/spatial.py
Geometry randomizationembodichain/lab/gym/envs/managers/randomization/geometry.py

3. Write the Functor

Follow the template for function-style or class-style (see above).

Key rules:

  • First argument is always env: EmbodiedEnv (use TYPE_CHECKING guard for the import)
  • Use from __future__ import annotations at the top
  • Use SceneEntityCfg for entity references, not raw strings
  • For observation functors: add shape key to FunctorCfg.extra dict
  • For randomization functors: second arg is env_ids: torch.Tensor | list[int]
  • For reward functors: return shape must be (num_envs,)
  • For condition functors: return ConditionResult with owned boolean satisfied/valid vectors and batch-aligned metric tensors on the environment device. Bind entities with SceneEntityCfg, keep metric schemas stable, and advance history only during TerminationManager.compute(); reset(env_ids) clears only selected rows. Reuse measured predicates from envs/objectives when applicable. Use a class functor when entity or parameter validation must run during binding, before reset context exists. Keep that validation in its constructor; the termination manager must not enumerate concrete condition implementations.

4. Update __all__

Add the new functor to the module's __all__ list. If no __all__ exists, create one. For observation implementations, re-export the functor from the observation package so existing config-name resolution finds it.

5. Write a Test

Place at tests/gym/envs/managers/test_<functor_type>.py (append to existing file if present).

For functors that don't need a live simulation, use mock objects (MockEnv, MockSim, etc.) following the pattern in tests/gym/envs/managers/test_reward_functors.py.

6. Run black

black embodichain/lab/gym/envs/managers/<module>.py
black tests/gym/envs/managers/test_<functor_type>.py

Common Mistakes

MistakeFix
Wrong first argument signatureObservation: (env, obs, ...), Reward: (env, obs, action, info, ...), Event/Randomization: (env, env_ids, ...)
Importing EmbodiedEnv at module levelUse TYPE_CHECKING guard to avoid circular imports
Forgetting SceneEntityCfg for entity refsAlways use SceneEntityCfg(uid="...") not bare strings
Returning wrong tensor shapeRewards must return (num_envs,), observations must match declared shape
Missing from __future__ import annotationsRequired in every file
Class-style functor not calling super().__init__Always call super().__init__(cfg, env)
Adding randomizer as standaloneRandomizations ARE events — they go in randomization/ but use EventCfg

Quick Reference

StepAction
1Identify manager type + function vs class style
2Write functor in the correct module file
3Update __all__ in that module
4Write test with mocks (no sim needed for most)
5Run black on changed files
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall