[choreo] Add PPLib commands and ChoreoLib events to specification (#701)

src-core/src/spec/traj.rs

@@ -388,6 +388,14 @@ pub struct TrajFile {
     pub params: Parameters<Expr>,
     /// The trajectory the robot will follow.
     pub traj: Trajectory,
+    /// The choreo events.
+    #[serde(default)]
+    pub events: Vec<EventMarker>,
+    /// The pplib commands to execute.
+    /// This is a compatibility layer for working with
+    /// the path planner library.
+    #[serde(default)]
+    pub pplib_commands: Vec<PplibCommandMarker>,
 }
 
 impl TrajFile {
@@ -402,3 +410,34 @@ impl TrajFile {
         serde_json::from_str(content).map_err(Into::into)
     }
 }
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PplibCommandMarker {
+    pub name: String,
+    pub target: Option<usize>,
+    pub traj_target_index: Option<usize>,
+    pub target_timestamp: Option<f64>,
+    pub offset: f64,
+    pub command: PplibCommand,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", tag = "type", content = "data")]
+pub enum PplibCommand {
+    Named { name: String },
+    Wait { wait_time: f64 },
+    Sequential { commands: Vec<PplibCommand> },
+    Parallel { commands: Vec<PplibCommand> },
+    Race { commands: Vec<PplibCommand> },
+    Deadline { commands: Vec<PplibCommand> },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EventMarker {
+    /// The name of the event.
+    pub event: String,
+    /// The offset from the beginning of the trajectory.
+    pub timestamp: f64,
+}

src/document/2025/v2025_0_0.ts

@@ -123,6 +123,8 @@ export interface Traj {
   params: ChoreoPath<Expr>;
   snapshot: ChoreoPath<number>;
   traj: Output;
+  events: EventMarker[];
+  pplibCommands: PplibCommandMarker<number>[];
 }
 
 export interface CircleObstacle<T extends ExprOrNumber> {
@@ -134,7 +136,7 @@ export interface CircleObstacle<T extends ExprOrNumber> {
 export type GroupCommand<T extends ExprOrNumber> = {
   type: "deadline" | "parallel" | "race" | "sequential";
   data: {
-    commands: Command<T>[];
+    commands: PplibCommand<T>[];
   };
 };
 export type WaitCommand<T extends ExprOrNumber> = {
@@ -149,11 +151,11 @@ export type NamedCommand = {
     name: string | null;
   };
 };
-export type Command<T extends ExprOrNumber> =
+export type PplibCommand<T extends ExprOrNumber> =
   | WaitCommand<T>
   | GroupCommand<T>
   | NamedCommand;
-export interface EventMarker<T extends ExprOrNumber> {
+export interface PplibCommandMarker<T extends ExprOrNumber> {
   name: string;
   target: WaypointID;
   trajTargetIndex: number | undefined;
@@ -162,5 +164,9 @@ export interface EventMarker<T extends ExprOrNumber> {
    * The timestamp along the trajectory of the waypoint this marker targeted on the last generation.
    */
   targetTimestamp: number | undefined;
-  command: Command<T>;
+  command: PplibCommand<T>;
+}
+export interface EventMarker {
+  event: string;
+  timestamp: number;
 }

src/document/DocumentManager.ts

@@ -16,8 +16,8 @@ import LocalStorageKeys from "../util/LocalStorageKeys";
 import { ObjectTyped } from "../util/ObjectTyped";
 import { safeGetIdentifier } from "../util/mobxutils";
 import {
-  Command,
-  EventMarker,
+  PplibCommand,
+  PplibCommandMarker,
   GroupCommand,
   NamedCommand,
   Project,
@@ -93,7 +93,7 @@ export type EnvConstructors = {
     radius: number
   ) => ICircularObstacleStore;
   CommandStore: (
-    command: Command<Expr> &
+    command: PplibCommand<Expr> &
       (
         | {
             data: WaitCommand<Expr>["data"] &
@@ -103,7 +103,7 @@ export type EnvConstructors = {
         | object
       )
   ) => ICommandStore;
-  EventMarkerStore: (marker: EventMarker<Expr>) => IEventMarkerStore;
+  EventMarkerStore: (marker: PplibCommandMarker<Expr>) => IEventMarkerStore;
   ConstraintData: ConstraintDataConstructors;
   ConstraintStore: <K extends ConstraintKey>(
     type: K,
@@ -113,18 +113,22 @@ export type EnvConstructors = {
   ) => IConstraintStore;
 };
 function getConstructors(vars: () => IVariables): EnvConstructors {
-  function commandIsNamed(command: Command<Expr>): command is NamedCommand {
+  function commandIsNamed(
+    command: PplibCommand<Expr>
+  ): command is NamedCommand {
     return Object.hasOwn(command.data, "name");
   }
   function commandIsGroup(
-    command: Command<Expr>
+    command: PplibCommand<Expr>
   ): command is GroupCommand<Expr> {
     return Object.hasOwn(command.data, "commands");
   }
-  function commandIsTime(command: Command<Expr>): command is WaitCommand<Expr> {
+  function commandIsTime(
+    command: PplibCommand<Expr>
+  ): command is WaitCommand<Expr> {
     return Object.hasOwn(command.data, "time");
   }
-  function createCommandStore(command: Command<Expr>): ICommandStore {
+  function createCommandStore(command: PplibCommand<Expr>): ICommandStore {
     return CommandStore.create({
       type: command.type,
       name: commandIsNamed(command) ? command.data.name : "",
@@ -201,7 +205,7 @@ function getConstructors(vars: () => IVariables): EnvConstructors {
       });
     },
     CommandStore: createCommandStore,
-    EventMarkerStore: (marker: EventMarker<Expr>): IEventMarkerStore => {
+    EventMarkerStore: (marker: PplibCommandMarker<Expr>): IEventMarkerStore => {
       return EventMarkerStore.create({
         name: marker.name,
         target: undefined,

src/document/EventMarkerStore.tsx

@@ -9,7 +9,7 @@ import {
   types
 } from "mobx-state-tree";
 import { moveItem } from "mobx-utils";
-import { Command, Expr } from "./2025/DocumentTypes";
+import { PplibCommand, Expr } from "./2025/DocumentTypes";
 import { WaypointID } from "./ConstraintDefinitions";
 import { WaypointScope } from "./ConstraintStore";
 import { Env } from "./DocumentManager";
@@ -58,7 +58,7 @@ export const CommandStore = types
         self.type === "sequential"
       );
     },
-    get serialize(): Command<Expr> {
+    get serialize(): PplibCommand<Expr> {
       if (self.type === "named") {
         return {
           type: "named",
@@ -84,7 +84,7 @@ export const CommandStore = types
     }
   }))
   .actions((self) => ({
-    deserialize(ser: Command<Expr>) {
+    deserialize(ser: PplibCommand<Expr>) {
       self.commands.clear();
       self.name = "";
       self.type = ser.type;

src/document/path/HolonomicPathStore.ts

@@ -44,7 +44,9 @@ export const HolonomicPathStore = types
           version: SAVE_FILE_VERSION,
           params: self.params.serialize,
           traj: self.traj.serialize,
-          snapshot: self.snapshot
+          snapshot: self.snapshot,
+          pplibCommands: [],
+          events: []
         };
       },
       lowestSelectedPoint(): IHolonomicWaypointStore | null {