The Clay Canvas plugin provides a 2D canvas system with world coordinate mapping, camera controls, and visual elements positioned in world units. It offers a complete solution for creating 2D game worlds with proper coordinate transformations and viewport management.

Getting Started

To use the Clay Canvas plugin in your QML files:

import Clayground.Canvas

Core Components

  • ClayCanvas - Main canvas managing viewport, coordinate system, and camera with Y-up orientation
  • Rectangle - Rectangle positioned and sized in world units
  • Text - Text element with world unit positioning and scalable font
  • Image - Image positioned and sized in world units
  • Poly - Polygon or polyline shape from vertex arrays in world units
  • Connector - Visual line connecting two items with automatic position tracking

Usage Examples

Basic Canvas Setup

import QtQuick
import Clayground.Canvas as Canv

Canv.ClayCanvas {
    id: canvas
    anchors.fill: parent

    // Define world boundaries
    worldXMin: -10
    worldXMax: 10
    worldYMin: -10
    worldYMax: 10

    // Set scale
    pixelPerUnit: 50

    // Enable debug info (press Space to toggle)
    showDebugInfo: true
}

Creating World Objects

Canv.Rectangle {
    canvas: canvas
    xWu: 0      // Center of world
    yWu: 0
    widthWu: 2
    heightWu: 1
    color: "red"
}

Canv.Text {
    canvas: canvas
    xWu: 0
    yWu: 2
    fontSizeWu: 0.5
    text: "Hello World!"
    color: "blue"
}

Canv.Image {
    canvas: canvas
    xWu: -5
    yWu: 5
    widthWu: 3
    heightWu: 3
    source: "player.png"
}

Drawing Shapes

// Draw a triangle
Canv.Poly {
    canvas: canvas
    vertices: [
        {x: 0, y: 0},
        {x: 2, y: 0},
        {x: 1, y: 2}
    ]
    fillColor: "green"
    strokeColor: "darkgreen"
    strokeWidth: 2
}

// Draw a path
Canv.Poly {
    canvas: canvas
    vertices: [
        {x: -5, y: -5},
        {x: -3, y: -3},
        {x: -1, y: -3},
        {x: 1, y: -5}
    ]
    strokeColor: "purple"
    strokeStyle: ShapePath.DashLine
}

Camera Following

Canv.ClayCanvas {
    id: canvas

    Canv.Rectangle {
        id: player
        canvas: canvas
        xWu: 0
        yWu: 0
        widthWu: 1
        heightWu: 1
        color: "orange"

        // Animate position
        NumberAnimation on xWu {
            from: -5; to: 5
            duration: 5000
            loops: Animation.Infinite
        }
    }

    // Camera follows the player
    observedItem: player
}

Visual Connections

Canv.Rectangle {
    id: nodeA
    canvas: canvas
    xWu: -2; yWu: 0
    widthWu: 1; heightWu: 1
    color: "blue"
}

Canv.Rectangle {
    id: nodeB
    canvas: canvas
    xWu: 2; yWu: 0
    widthWu: 1; heightWu: 1
    color: "red"
}

Canv.Connector {
    from: nodeA
    to: nodeB
    color: "green"
    strokeWidth: 3
    style: ShapePath.DashLine
}

Best Practices

  1. World Units: Always use world units (Wu) for positioning and sizing to ensure consistent scaling.

  2. Canvas Reference: Always set the canvas property for visual elements to ensure proper coordinate transformation.

  3. Performance: For many objects, consider using a single Poly with multiple disconnected segments rather than many individual items.

  4. Camera Control: Use observedItem for automatic camera following, or manually control viewport position.

  5. Debug Mode: Use showDebugInfo during development to understand coordinate mappings.

Technical Implementation

The Clay Canvas plugin implements:

  • Coordinate System: Cartesian coordinates with Y-up orientation
  • Viewport Management: Flickable-based viewport with bounds checking
  • Automatic Scaling: Device scaling and zoom factor support
  • Debug Overlay: Grid display and coordinate information
  • Keyboard Navigation: Optional IJKL navigation with E/D zoom controls

The canvas uses Qt Quick’s scene graph for efficient rendering and supports dynamic creation of visual elements at runtime.