🖍️ Sketch Paper

Sketch Paper is a web-component for creating drawing applications. It's the software behind crayon.town.

Check out the live demo at sketchpaper.ink to see Sketch Paper in action.

Installation

npm i @sketch-paper/core

Usage

Sketch-paper is a web component, meaning you use it like this:

// import the library
import '@sketch-paper/core';

<!-- add it to your html -->
<sketch-paper ...></sketch-paper>

// once <sketch-paper/> is mounted, you must initialize the component.
const sketchPaperElement = getElementsByTagName('sketch-paper')[0];
sketchPaperElement.initialize(settings);

Simple Example

Sketch paper works with all frameworks. Here's an example showing it with Vue.js.

<script setup lang="ts">
  import { ref, onMounted } from 'vue';

  import { BrushKinds } from '@sketch-paper/core';

  const sketchPaperRef = ref();
  onMounted(() => {
    sketchPaperRef.value?.initialize({
      tileCountX: 0, // 0 means infinite
      tileCountY: 0, // 0 means infinite
      brushes: [BrushKinds.Crayon],
    });
  });
</script>

<template>
  <sketch-paper
    ref="sketchPaperRef"
    style="width: 100vw; height: 100vh"
    :brush-color="brush.color"
    :brush-kind="brush.kind"
    :brush-size="brush.size"
  >
  </sketch-paper>
</template>

Check out /examples for more.

Settings

// Settings are passed to the component via
sketchPaperElement.initialize(settings);

All settings are optional.

| field | Default | Description | | ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | brushes | [BrushKinds.Crayon] | An array of brushes to load. | | minZoom | 0.25 | How far out the camera can zoom. | | maxZoom | 10 | How far in the camera can zoom. | | startX | 0 | Camera starting position X. | | startY | 0 | Camera starting position Y. | | tileCountX | 1 | Number of tiles in the x direction. 0 means infinite* tiles | | tileCountY | 1 | Number of tiles in the y direction. 0 means infinite* tiles | | tileWidth | 2048 | The tile width in pixels. | | tileHeight | 2048 | The tile height in pixels. | | baseUrl | '' | Defines where Sketch Paper looks for tile images. Must be a public URL with the format${baseUrl}/${tileX}_${tileY}.png (tileX, tileY are the tile indices). Empty string means Sketch Paper will not try to load the tiles from remote images. | | baseColor | #C2BCB0 | Default color of the tiles. | | backgroundColor | #FFFFFF | Color outside of the drawing surface. | | allowUndo | true | Boolean for undo/redo functionality. undo = ctrl+z, redo = ctrl+y or ctrl+shift+z | | tileLoadingConcurrency | 3 | How many tiles can be loading at once, useful when you're using "baseUrl". | | maxTiles | 20 | How many tiles can be loaded in memory at once. | | loadingImg | '' | A URL pointing to an image to show while a tile is loading. The loading image doesn't have to be the same resolution as the tile. | | maxSegmentLength | 0 | How long a segment is a allowed to be. 0 means infinte. |

* Infinite actually means 2^32 pixels, the canvas will loop after that.

Attributes

Add attributes directly to the HTML directive.

<sketch-paper ... brush-color="#ff0000" brush-size="50"></sketch-paper>

<sketch-paper> uses the following attributes. Unlike the settings, these can be updated during runtime. | Attribute | Default | Description | | -------- | ------- | ------- | | brush-color | #000000 | Hex string, it can also include opacity value, eg: #00000000 | brush-kind | BrushKinds.None | None, Crayon, Marker, Paint | brush-size | 10 | The width and height in pixels of the brush tip | action-left-mouse | PointerActions.Draw | None, Draw, Pan | action-middle-mouse | PointerActions.Pan | None, Draw, Pan | action-right-mouse | PointerActions.Pan | None, Draw, Pan | action-wheel | WheelActions.Zoom | None, Zoom, Scroll

Events

Stay informed by listening for events.

<sketch-paper ... @sp-move="handleMove" />

function handleMove(event: SpMoveEvent) {
    console.log(event.detail) // { x: 123; y: 456 }
}

The <sketch-paper> component emits the following events:

| Event | Payload | Description | | ------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------- | | sp-draw | DrawSegment[] | Emitted each frame when a new segment is drawn. The payload includes a draw segment for each tile that was drawn on. | | sp-move | { x: number; y: number } | Emitted when the camera is translated. | | sp-zoom | { zoom: number } | Emitted when the camera is zoomed. | | sp-tile-load | index: [number, number] | Emitted when a tile image is loaded. |