DOCSEARCHbyAlgolia
Submit Docs

sketchbook

repository·master·Indexed 23 days ago

https://github.com/swift502/sketchbook

A web-based game engine built on three.js and cannon.js, version 0.4.0. It is optimized for third-person character controls and vehicle mechanics (cars, airplanes, and helicopters). Key features include a raycast character controller, a general state system, character AI, and a physics-based world with variable timescale and FXAA anti-aliasing. It includes utilities for spring physics simulations, GLTF asset loading, and custom input handling via the IInputReceiver interface.

Tokens
3.7K
Snippets
5
Records
33
Agent score
82%

What's inside sketchbook

  1. What is Sketchbook

    master

    Sketchbook is a simple web-based game engine built on three.js and cannon.js. It is specifically designed for third-person character controls and related gameplay mechanics, serving as a playground for recreating conventional modern game mechanics in a general way.

    Key features include:

    • World: Three.js scene integration, Cannon.js physics, variable timescale, frame skipping, and FXAA anti-aliasing.
    • Characters: Third-person camera, raycast character controller with capsule collisions, a general state system, and character AI.
    • Vehicles: Support for cars, airplanes, and helicopters.

  2. Use Sketchbook via NPM

    master

    To integrate Sketchbook into a modern JavaScript project, install it via npm and import the World class.

    Note: Sketchbook must be served from a local server (such as http-server or webpack-dev-server) to allow loading of external assets.

    npm i sketchbook
    import { World } from 'sketchbook';

const world = new World('scene.glb');

  3. Use Sketchbook via Script Tag

    master

    To use Sketchbook directly in an HTML file, include the minified script and instantiate a new Sketchbook.World by passing the path to a .glb scene file (e.g., exported from Blender).

    Note: Sketchbook must be served from a local server (such as http-server or webpack-dev-server) to allow loading of external assets.

  4. Initialize the Sketchbook World

    master

    To start a Sketchbook simulation, instantiate the World class. If you provide a path to a GLTF scene file, the engine will automatically load the scene, set up physics colliders, paths, and scenarios based on the userData defined in the GLTF file. If no path is provided, an empty world with a sky is initialized.

    GLTF Integration Requirements: To have the World automatically process elements in your GLTF, use the following userData patterns:

    • Physics: Set userData.data = 'physics'. Use userData.type = 'box' for simple box colliders or userData.type = 'trimesh' for complex mesh colliders.
    • Paths: Set userData.data = 'path'.
    • Scenarios: Set userData.data = 'scenario'.

  5. Use RelativeSpringSimulator for physics-based movement

    master

    The RelativeSpringSimulator class provides a spring-based physics simulation designed to output relative movement values. Unlike standard simulators that return absolute positions, this simulator calculates the difference between the current interpolated position and the previous one, making it useful for applying incremental offsets to objects.

    Constructor Parameters

    • fps: Frames per second for the simulation.
    • mass: The mass of the simulated object.
    • damping: The damping coefficient (resistance).
    • startPosition (optional): The initial position (defaults to 0).
    • startVelocity (optional): The initial velocity (defaults to 0).

    Key Properties

    • target: The value the spring is attempting to reach.
    • position: The current relative position calculated during the last simulate() call.
    • velocity: The current velocity.
    • cache: An array of SimulationFrame objects used to store state for interpolation.

  6. Configure SpringSimulator via constructor

    master

    When instantiating SpringSimulator, you can configure the physical properties of the spring and the simulation frequency.

    Parameters:

    • fps (number): Frames per second for the simulation.
    • mass (number): The mass of the object.
    • damping (number): The damping coefficient (resistance).
    • startPosition (number, optional): The initial position. Defaults to 0.
    • startVelocity (number, optional): The initial velocity. Defaults to 0.

  7. Load GLTF assets with LoadingManager

    master
    Use loadGLTF to load 3D models via a GLTF path. This method automatically tracks the loading progress and notifies the manager when the asset is ready. You must provide a callback function that receives the loaded GLTF object. Once all registered assets are loaded, the LoadingManager will automatically hide the loading screen and show the user interface (unless a custom onFinishedCallback is provided).

  8. Create a welcome screen with createWelcomeScreenCallback

    master
    To show a welcome/instructional dialog after assets have finished loading, call createWelcomeScreenCallback with a Scenario object. This sets an internal onFinishedCallback that triggers a SweetAlert2 popup. When the user clicks 'Play' in the popup, the world's time scale is set to 1 (resuming simulation) and the user interface becomes visible.

  10. Implement custom input handling with IInputReceiver

    master

    To handle user input (mouse, keyboard, wheel) within Sketchbook, you should implement the IInputReceiver interface and register it with the InputManager using setInputReceiver().

    When an IInputReceiver is set, the InputManager will automatically call its lifecycle methods:

    1. inputReceiverInit(): Called immediately when the receiver is set.
    2. inputReceiverUpdate(unscaledTimeStep): Called every frame during the InputManager.update() cycle.
    3. handleMouseButton(event, buttonId, isDown): Triggered on mouse down/up.
    4. handleMouseMove(event, movementX, movementY): Triggered on mouse movement.
    5. handleKeyboardEvent(event, keyCode, isDown): Triggered on key down/up.
    6. handleMouseWheel(event, deltaY): Triggered on mouse wheel movement.

    By default, if no receiver is provided, the InputManager attempts to automatically set the world.cameraOperator as the input receiver.

  11. Register custom updatables

    master

    If you have custom logic that needs to run every frame, implement the IUpdatable interface and register it with the World. Updatables are sorted by their updateOrder property before being executed.

    • registerUpdatable(registree: IUpdatable): Adds an object to the internal update loop.
    • unregisterUpdatable(registree: IUpdatable): Removes an object from the update loop.