Tools

Tools allow you to modify a model at design time programmatically. You can create your own tools that act on an Entity, the World or a Component. There are just two functions you need to implement:

• The valid() function determines whether the Tool should be visible in the explorer/inspector.
• The execute() function gets called when you execute the tool.

Examples

Entity Tool

The example below demonstrates how to create a tool that moves an entity down so that it rests on the floor.

import { type Entity, Vec3, Icon, Tool } from "prototwin";

@Icon("bx-arrow-to-bottom")
export class MoveToFloor extends Tool<Entity> {
    override valid(entity: Entity): boolean {
        return true;
    }

    override execute(entity: Entity): void {
        const bbox = entity.worldBoundingBox;
        const offset = new Vec3(0, bbox.min.y, 0);
        entity.worldPosition = Vec3.subtract(entity.worldPosition, offset);
    }
}

World Tool

The example below demonstrates how to create a tool that groups all the selected entities.

import { type World, Editor, Icon, Tool } from "prototwin";

@Icon("mdi:family")
export class Group extends Tool<World> {
    override valid(world: World): boolean {
        return Editor.selection.length > 0;
    }

    override execute(world: World): void {
        const parent = world.create("Parent");
        const selection = Editor.selection;
        for (const entity of selection) {
            entity.reparent(parent);
        }

        selection.clear();
        selection.add(parent);
    }
}

Component Tool

The example below demonstrates how to create a tool that applies a force to the physics body of an entity. Note that, this particular tool will only apply a force if the simulation has been initialized.

import { type PhysicsComponent, Vec3, Icon, Tool, Body } from "prototwin";

@Icon("bx:arrow-from-left")
export class ApplyForce extends Tool<PhysicsComponent> {
    public force: Vec3 = Vec3.zero;

    override valid(component: PhysicsComponent): boolean {
        return component.body === Body.Dynamic;
    }

    override execute(component: PhysicsComponent): void {
        component.applyForce(this.force);
    }
}

Using Tools

The procedure is slightly different for executing entity, component and world tools:

• Execute a entity tool by right clicking on any entity in the explorer.
• Execute a world tool by right clicking in the explorer pane.
• Execute a component tool by clicking on the ellipsis the right of the component’s name.

The valid() condition must be satisfied for the tool to be visible in the explorer/inspector.

Properties

If your tool has public properties, a dialog window will open that allows you to configure the properties before the execute() method is called on the tool. You can also use decorators to configure how the properties of tools should be displayed.