[Canonical page](<https://docs.dhtmlx.com/planning-engine/java/api/project-level/>)
[Full documentation index](<https://docs.dhtmlx.com/planning-engine/llms.txt>)


# Project#level

Resolves resource overallocation in a [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>). It runs [`solve(null, …)`](<https://docs.dhtmlx.com/planning-engine/java/api/project-solve.md>) with default options first, then writes persistent `levelingDelay` and `pauses` edits and accepts the leveled state as the baseline.

## Signature

```java
public LevelingResult level(LevelingOptions options)
```

Synchronous and CPU-only. Changes the project's state. Not synchronized: serialize calls on one instance.

## Parameters

| Name | Type | Description |
|---|---|---|
| `options` | [`LevelingOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-options.md>) | Scope, order, basis and how leveling may move tasks. Must not be `null` |

## Behavior

- Forward scheduling only.
- On a cyclic project, it returns the initial solve's result with [`rounds`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-result.md>) `= 0`.
- The leveled dates replace the baseline. To see leveling without committing it, call `level` on a [`copy()`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md#copy>).
- Known bug: the call doesn't return when an assignment asks for more units than its resource can ever supply, for example `value` `1.25` on capacity `1`.

## Returns

A [`LevelingResult`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-result.md>). The project keeps its `schedule` as the baseline and shares it with copies. Treat `schedule` as read-only, or call `deepClone()` before changing it.

## Errors

All exceptions are unchecked.

| Error | When |
|---|---|
| [`InputException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/input-exception.md>) | An unknown id in `options.scope.resources` or `options.scope.tasks` (`path` is `scope.resources` / `scope.tasks`); the project has [`config.scheduleFromEnd`](<https://docs.dhtmlx.com/planning-engine/java/api/data/scheduling-config.md>) `= true` (`path` is `config.schedule_from_end`) |
| [`ProjectException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/project-exception.md>) with `code == ProjectError.NEEDS_RESYNC` | Thrown by the initial solve |
| `NullPointerException` | `options` is `null` |

## Example

Level two tasks that share one resource, first on a copy, then on the project itself.

```java
import java.util.List;
import org.dhtmlx.plen.*;

public class LevelExample {
  public static void main(String[] args) throws Exception {
    Moment monday = Moment.fromYmdHm(2026, 8, 10, 8, 0);
    ProjectData data = new ProjectData()
        .withTasks(List.of(
            new TaskData(Id.str("a")).withStartDate(monday).withDuration(2.0),
            new TaskData(Id.str("b")).withStartDate(monday).withDuration(2.0)))
        .withResources(List.of(new ResourceData().withId(Id.str("dev"))))
        .withAssignments(List.of(
            new AssignmentData().withTask(Id.str("a")).withResource(Id.str("dev")).withValue(1.0),
            new AssignmentData().withTask(Id.str("b")).withResource(Id.str("dev")).withValue(1.0)));

    Project project = new Project();
    project.solve(data, new SolveOptions());

    // A proposal: level a cheap copy, the project keeps its dates.
    Project draft = project.copy();
    LevelingResult proposal = draft.level(new LevelingOptions());
    for (Mutation update : proposal.schedule.updates) {
      System.out.println("task " + update.id + " delay " + update.levelingDelay);
      // task b delay 2.0
    }

    // Commit: level the project itself.
    LevelingResult leveled = project.level(new LevelingOptions());
    System.out.println(leveled.rounds + " round(s)");
  }
}
```

## Related

- [`LevelingOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-options.md>) - scope, order, basis and how tasks may move
- [`LevelingResult`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-result.md>) - the leveled schedule and what changed
- [Leveling resources](<https://docs.dhtmlx.com/planning-engine/java/resources-and-assignment/leveling-resources.md>) - delays, pauses, selection order and reading the result
- [Preview leveling](<https://docs.dhtmlx.com/planning-engine/java/how-to/preview-leveling.md>) - leveling a copy without committing it
- [Clear leveling](<https://docs.dhtmlx.com/planning-engine/java/how-to/clear-leveling.md>) - removing leveling delays and pauses