miaoda-game-grid-cocos

Use this Cocos Creator adapter to place nodes on a centered tile grid, animate them between tiles, and convert screen taps back to the same tile coordinates used by miaoda-game-grid-core.

The adapter does not create tiles or own board state. Your game creates and pools nodes; GridView positions them, while GridInput reports { x, y } taps.

Install

pnpm add miaoda-game-grid-core miaoda-game-grid-cocos

Cocos Creator provides the optional cc peer dependency at runtime.

Place nodes and receive taps

import { GridInput, GridInputEvent, GridView } from 'miaoda-game-grid-cocos';
import type { TileXY } from 'miaoda-game-grid-core';

const layout = { cols: 13, rows: 13, cell: 48 };
const gridView = gridNode.addComponent(GridView).setup(layout);
const gridInput = gridNode.addComponent(GridInput).setup(layout);

gridView.place(tankNode, 0, 0);

gridNode.on(GridInputEvent.TILE_TAP, (tile: TileXY) => {
  selectTile(tile);
});

await gridView.moveTo(tankNode, 1, 0, 0.15);

GridView.moveTo measures duration in seconds. A non-positive or non-finite duration places the node immediately. The returned promise resolves when the tween finishes, so you can animate a route one tile at a time:

for (const tile of path.slice(1)) {
  await gridView.moveTo(unitNode, tile.x, tile.y, 0.12);
}

Coordinate convention

The grid is centered on gridNode:

• Tile (0, 0) is the top-left.
• X increases right and Y increases down.
• cell is the width and height of one square tile in UI pixels.
• cols and rows must match the core grid's width and height.

If the grid center is offset from the screen center, give the same UI-pixel offset to input:

gridInput.setGridOffset(gridCenterX, gridCenterY);

GridInput reads Cocos Creator's live visible size, so do not pre-adjust touch coordinates using the design resolution. Set gridInput.locked = true while animations or modal UI should ignore board taps.

Hex layout

import {
  createCocosHexLayout,
  localToHexTile,
  setHexNodePosition,
} from 'miaoda-game-grid-cocos';

const hexLayout = createCocosHexLayout({
  orientation: 'pointy',
  size: { x: 32, y: 32 },
  origin: { x: 0, y: 0 },
});
setHexNodePosition(unitNode, hexLayout, { x: 3, y: 4 }, 'odd-r');
const tile = localToHexTile(hexLayout, nodeLocalPoint, 'odd-r');

The adapter fixes Cocos node-local Y-up coordinates and preserves the caller-owned Z plane. Convert UI/world touches with the node's UITransform before picking. Projection, vertices, and cube rounding live once in grid-core; physics and navigation remain Cocos host queries.

Use pathfinding results

The adapter and core share the TileXY shape. A path from findPath can be passed directly to GridView without coordinate conversion.

import { findPath } from 'miaoda-game-grid-core';

const path = findPath(
  { width: layout.cols, height: layout.rows },
  selectedTile,
  targetTile,
  { isBlocked },
);

if (path) {
  gridInput.locked = true;
  for (const tile of path.slice(1)) {
    await gridView.moveTo(unitNode, tile.x, tile.y, 0.12);
  }
  gridInput.locked = false;
}

Usage notes

• GridView does not render a board or highlights. Create those nodes yourself and place them with gridView.place(...) so they use the same layout math.
• Nodes created in code must use a layer visible to your UI camera. A common choice is node.layer = gridNode.layer.
• GridInput listens for global touch-end events and removes its listener when the component is destroyed.
• Higher-level gestures such as dragging, swapping, and select-then-move belong in the game or a mechanic-specific package such as miaoda-game-match3-cocos.