DHTMLX Planning Engine Documentation

Metrics#

Measures of one scored state compared with the baseline: finish dates, resource overload, conflict and cycle counts, and a single cost for ranking. Project#evaluate returns one for the baseline and for each stage of each candidate; Project#suggestAssignments returns one for its proposal.

Declaration#

interface Metrics {
  finish: {
    project: Shift | null;
    tasks: { id: Id; finish: Shift | null }[];
  };
  overload: {
    total: Amount;
    resources: ResourceOverload[];
    focus: { task: Id; resources: ResourceOverload[] | null }[];
  };
  conflicts: Amount;
  cycles: Amount;
  cost: number;
}

Fields#

Field Type Description
finish.project Shift | null Project finish: the latest end over scheduled tasks. null when the state has no tasks.
finish.tasks { id, finish }[] One entry per focus task, in focus order. finish is the task's end as a Shift, or null when the task doesn't exist in this state. Empty without focus.
overload.total Amount Overload summed over all resources.
overload.resources ResourceOverload[] Overload per resource, for every resource that's non-zero in this state or in the baseline. Resources overloaded in this state come first, then those overloaded only in the baseline.
overload.focus { task, resources }[] One entry per focus task: overload per resource over the time buckets the task spans, listed and ordered like overload.resources. resources is null when the task doesn't exist in this state. A milestone spans no bucket. Empty without focus.
conflicts Amount Number of scheduling conflicts.
cycles Amount Number of dependency cycles.
cost number Ranking score, lower is better: max(0, finish.project.delta) + overload.total.value + 1000 × (conflicts.value + cycles.value).

Overload is the sum over time buckets of max(0, load − capacity) for a resource. Its unit is capacity × buckets: on a day basis, 2 means two resource-days over capacity. For how the bucket basis is chosen and how to read these numbers, see Evaluating alternatives.

Focus tasks come from the focus option of Project#evaluate.

Shift#

A finish date and its distance from the baseline finish.

Field Type Description
date DateValue The finish date. A string, or a local Date when the project was created with dates: "date".
delta number Working time from the baseline finish to date, in config.duration_unit. Positive when later. A task's delta is measured on the task's calendar, the project's on the global calendar. 0 in the baseline's own metrics.

Amount#

A count or quantity and its change from the baseline.

Field Type Description
value number The value in this state.
delta number value minus the baseline's value. 0 in the baseline's own metrics.

ResourceOverload#

Field Type Description
resource Id Resource id.
overload Amount The resource's overload and its change from the baseline.

LeveledMetrics#

Metrics of a leveled state: every Metrics field plus a summary of the leveling run. Returned as leveled when leveling is requested.

interface LeveledMetrics extends Metrics {
  converged: boolean;
  rounds: number;
  windows: number;
}
Field Type Description
converged boolean Whether the leveling run converged.
rounds number Number of leveling rounds run.
windows number Number of overallocation windows left after leveling, for any reason.
Note

Leveled metrics have the same fields as Metrics plus converged, rounds and windows.

Used by#

Example#

A candidate that finishes one day later and removes two resource-days of overload from resource "dev1":

const metrics = {
  finish: {
    project: { date: "2026-03-20 17:00", delta: 1 },
    tasks: [{ id: "build", finish: { date: "2026-03-18 17:00", delta: 1 } }],
  },
  overload: {
    total: { value: 0, delta: -2 },
    resources: [{ resource: "dev1", overload: { value: 0, delta: -2 } }],
    focus: [{ task: "build", resources: [{ resource: "dev1", overload: { value: 0, delta: -2 } }] }],
  },
  conflicts: { value: 0, delta: 0 },
  cycles: { value: 0, delta: 0 },
  cost: 1,
};