Obstacle

A static, axis-aligned box barrier that carries collision semantics for movement, bullets, and line of sight.

What it does

Obstacle marks an entity as a solid box on the play field — movement is always blocked, while blocksBullets and blocksSight distinguish full-height walls from low cover. It has no per-frame System of its own: it's static collision data plus pure helper math (resolveCircleVsBox, segmentIntersectsBox) and a collectObstacleBoxes(world) query. Gameplay systems (movement, bullets, line of sight) call that query each frame to snapshot live obstacle footprints and resolve collisions themselves. The XZ footprint is derived from halfWidth/halfDepth centered on the sibling MeshPrimitive's position.

Use it in a scene

A scene is just data — a list of entities, each with its components. At startup the SceneLoader turns this JSON into a live world; edit the file and reload to rebuild it.

Fastest path

bjs download scene Obstacle

Pulls this exact scene into your project and runs it — no copy-paste. Add --all to grab the components and assets it needs too.

Or build it from scratch with the bjs CLI:

1Scaffold a project
```
npm create @babylonjsmarket/arcade@latest my-game
```
World, renderer, and dev server — ready to run.
2Install dependencies
```
cd my-game && npm install
```
3Add Obstacle
```
bjs download Obstacle
```
Copies its source into src/ so the scene resolves.
First time? Run bjs login once.
4Paste the scene into src/scenes/arcade-room.ts and run
```
npm run dev
```
SceneLoader builds the world from the JSON; reload to rebuild.

JSON

{
  "Wall": {
    "components": {
      "MeshPrimitive": {
        "primitive": "box",
        "width": 4,
        "height": 2,
        "depth": 1,
        "position": [0, 1, 0],
        "material": { "diffuseColor": [0.35, 0.18, 0.45] }
      },
      "Obstacle": { "halfWidth": 2, "halfDepth": 0.5, "blocksSight": true, "blocksBullets": true }
    }
  }
}

Props

halfWidth (number, default 1) — half-extent of the box footprint along X.
halfDepth (number, default 1) — half-extent of the box footprint along Z.
blocksSight (boolean, default true) — true for a full-height wall that breaks line of sight; false for low cover that doesn't.
blocksBullets (boolean, default true) — true for a full-height wall that stops bullets; false for low cover that lets them through.

Dependencies

MeshPrimitive — supplies the box's world position; collectObstacleBoxes reads it together with halfWidth/halfDepth to build each obstacle's XZ footprint.

Notes

Movement is always blocked regardless of flags; only bullets and sight are configurable via blocksBullets / blocksSight.
halfWidth/halfDepth should match the sibling MeshPrimitive box (width/depth ÷ 2) so the collision footprint lines up with the rendered mesh.
collectObstacleBoxes is cheap and meant to be rebuilt each frame by consumers rather than cached; it skips inactive entities and any obstacle missing a MeshPrimitive.

Obstacle.core.ts

Obstacle — pure core.

A solid, axis-aligned box barrier on the play field. Its XZ footprint (halfWidth/halfDepth) comes from the sibling MeshPrimitive's box; this component carries the collision semantics:

Movement is ALWAYS blocked — neither robots nor the player pass through. - blocksBullets — full-height walls stop bullets; low cover lets them through. - blocksSight — full-height walls break line of sight; low cover doesn't.

Consumed by EnemySystem (movement + LOS), BulletSystem (bullet stops), and TwinStickShooterSystem (player movement). The collision math below is pure so it's unit-testable without a renderer.

Obstacle.core.ts

import { Component } from '@babylonjsmarket/ecs'

export interface ObstacleInput {
  /** XZ half-extents of the box footprint. */
  halfWidth?: number
  halfDepth?: number
  /** Full-height wall breaks line of sight (low cover doesn't). */
  blocksSight?: boolean
  /** Full-height wall stops bullets (low cover lets them through). */
  blocksBullets?: boolean
}

export class ObstacleComponent extends Component {
  halfWidth: number
  halfDepth: number
  blocksSight: boolean
  blocksBullets: boolean

  constructor(data: ObstacleInput = {}) {
    super()
    this.halfWidth = data.halfWidth ?? 1
    this.halfDepth = data.halfDepth ?? 1
    this.blocksSight = data.blocksSight ?? true
    this.blocksBullets = data.blocksBullets ?? true
  }

  serialize(): ObstacleInput {
    return {
      halfWidth: this.halfWidth,
      halfDepth: this.halfDepth,
      blocksSight: this.blocksSight,
      blocksBullets: this.blocksBullets,
    }
  }
}

/** An axis-aligned box footprint in the XZ plane. */
export interface BoxBounds {
  minX: number
  maxX: number
  minZ: number
  maxZ: number
}

Push a circle (centre cx,cz, radius r) out of an AABB so it no longer overlaps, choosing the least-penetration axis. Returns the corrected [x, z] (unchanged if the circle is already clear of the box).

Obstacle.core.ts

export function resolveCircleVsBox(
  cx: number,
  cz: number,
  r: number,
  box: BoxBounds,
): [number, number] {
  // Closest point on the box to the circle centre.
  const nx = cx < box.minX ? box.minX : cx > box.maxX ? box.maxX : cx
  const nz = cz < box.minZ ? box.minZ : cz > box.maxZ ? box.maxZ : cz
  const dx = cx - nx
  const dz = cz - nz
  const d2 = dx * dx + dz * dz
  if (d2 > r * r) return [cx, cz] // not touching

  if (d2 > 1e-8) {
    // Centre is outside the box but the circle clips an edge/corner — push
    // straight out along the contact normal.
    const d = Math.sqrt(d2)
    const push = r - d
    return [cx + (dx / d) * push, cz + (dz / d) * push]
  }

  // Centre is inside the box — eject through the nearest face.
  const toMinX = cx - box.minX
  const toMaxX = box.maxX - cx
  const toMinZ = cz - box.minZ
  const toMaxZ = box.maxZ - cz
  const nearestX = Math.min(toMinX, toMaxX)
  const nearestZ = Math.min(toMinZ, toMaxZ)
  if (nearestX < nearestZ) {
    return [toMinX < toMaxX ? box.minX - r : box.maxX + r, cz]
  }
  return [cx, toMinZ < toMaxZ ? box.minZ - r : box.maxZ + r]
}

Does segment A→B (XZ) intersect the AABB? True if it crosses or either endpoint is inside. Liang–Barsky slab clipping.

Obstacle.core.ts

export function segmentIntersectsBox(
  ax: number,
  az: number,
  bx: number,
  bz: number,
  box: BoxBounds,
): boolean {
  const dx = bx - ax
  const dz = bz - az
  let t0 = 0
  let t1 = 1
  // Clip the parameter range [t0,t1] against one slab boundary. Returns false
  // if the segment falls entirely outside it.
  const clip = (p: number, q: number): boolean => {
    if (p === 0) return q >= 0 // parallel to this slab — inside iff q >= 0
    const t = q / p
    if (p < 0) {
      if (t > t1) return false
      if (t > t0) t0 = t
    } else {
      if (t < t0) return false
      if (t < t1) t1 = t
    }
    return true
  }
  if (!clip(-dx, ax - box.minX)) return false
  if (!clip(dx, box.maxX - ax)) return false
  if (!clip(-dz, az - box.minZ)) return false
  if (!clip(dz, box.maxZ - az)) return false
  return t0 <= t1
}

Obstacle.ts

eslint-disable babylonjsmarket/require-contract-test -- Obstacle has no System (it's static collision data + world-query helpers consumed by other systems), so there's no mechanic to run runMechanicContract against. The component + math are covered by Obstacle.core.test.ts. The rule matches Components/{Name}/{Name}.ts purely by filename, so disable it here.

Obstacle.ts — world-side helper for the Obstacle component.

Obstacles have no per-frame System of their own: they're static boxes created by ObstacleFieldSystem and read by the gameplay systems (Enemy, Bullet, TwinStickShooter). This module re-exports the pure core and provides the one impure bit — scanning the World for live obstacle footprints.

Obstacle.ts

import type { World } from '@babylonjsmarket/ecs'
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive'
import { ObstacleComponent } from './Obstacle.core'

export {
  ObstacleComponent,
  resolveCircleVsBox,
  segmentIntersectsBox,
  type ObstacleInput,
  type BoxBounds,
} from './Obstacle.core'

/** A collected obstacle footprint plus its collision flags. */
export interface ObstacleBox {
  minX: number
  maxX: number
  minZ: number
  maxZ: number
  blocksSight: boolean
  blocksBullets: boolean
}

Snapshot the live obstacle boxes (XZ footprint from each obstacle's sibling MeshPrimitive). Cheap — a scene has only a handful of obstacles — so callers rebuild this each frame rather than caching.

Obstacle.ts

export function collectObstacleBoxes(world: World): ObstacleBox[] {
  const boxes: ObstacleBox[] = []
  for (const e of world.getEntitiesWithComponent(ObstacleComponent)) {
    if (!e.active) continue
    const o = e.get(ObstacleComponent)
    const m = e.get(MeshPrimitiveComponent)
    if (!o || !m) continue
    boxes.push({
      minX: m.position[0] - o.halfWidth,
      maxX: m.position[0] + o.halfWidth,
      minZ: m.position[2] - o.halfDepth,
      maxZ: m.position[2] + o.halfDepth,
      blocksSight: o.blocksSight,
      blocksBullets: o.blocksBullets,
    })
  }
  return boxes
}

Obstacle.core.test.ts

9 ✓

ObstacleComponent

defaults to a solid full obstacle
serialize round-trips

resolveCircleVsBox

leaves a circle that is clear of the box untouched
pushes a circle clipping the +X face straight out
ejects a circle whose centre is inside through the nearest face

segmentIntersectsBox

detects a segment passing through the box
is false for a segment that misses the box
is true when an endpoint is inside the box
is false for a segment that stops short of the box

Last run 2026-07-17

Obstacle.core.test.ts

import { describe, it, expect } from 'vitest'
import {
  ObstacleComponent,
  resolveCircleVsBox,
  segmentIntersectsBox,
  type BoxBounds,
} from './Obstacle.core'

const box: BoxBounds = { minX: -1, maxX: 1, minZ: -1, maxZ: 1 }

describe('ObstacleComponent', () => {
  it('defaults to a solid full obstacle', () => {
    const c = new ObstacleComponent()
    expect(c.halfWidth).toBe(1)
    expect(c.halfDepth).toBe(1)
    expect(c.blocksSight).toBe(true)
    expect(c.blocksBullets).toBe(true)
  })

  it('serialize round-trips', () => {
    const a = new ObstacleComponent({ halfWidth: 2, halfDepth: 0.5, blocksSight: false, blocksBullets: false })
    const b = new ObstacleComponent(a.serialize())
    expect(b.halfWidth).toBe(2)
    expect(b.halfDepth).toBe(0.5)
    expect(b.blocksSight).toBe(false)
    expect(b.blocksBullets).toBe(false)
  })
})

describe('resolveCircleVsBox', () => {
  it('leaves a circle that is clear of the box untouched', () => {
    expect(resolveCircleVsBox(5, 0, 0.5, box)).toEqual([5, 0])
  })

  it('pushes a circle clipping the +X face straight out', () => {
    // Centre at x=1.3 (just outside the +X face at 1), radius 0.5 → overlaps by
    // 0.2; should be pushed to x = 1.5 (face + radius).
    const [x, z] = resolveCircleVsBox(1.3, 0, 0.5, box)
    expect(x).toBeCloseTo(1.5, 5)
    expect(z).toBeCloseTo(0, 5)
  })

  it('ejects a circle whose centre is inside through the nearest face', () => {
    // Centre near the +X face from inside → ejected out the +X side.
    const [x, z] = resolveCircleVsBox(0.8, 0, 0.5, box)
    expect(x).toBeCloseTo(1.5, 5)
    expect(z).toBeCloseTo(0, 5)
  })
})

describe('segmentIntersectsBox', () => {
  it('detects a segment passing through the box', () => {
    expect(segmentIntersectsBox(-3, 0, 3, 0, box)).toBe(true)
  })

  it('is false for a segment that misses the box', () => {
    expect(segmentIntersectsBox(-3, 3, 3, 3, box)).toBe(false)
  })

  it('is true when an endpoint is inside the box', () => {
    expect(segmentIntersectsBox(0, 0, 5, 5, box)).toBe(true)
  })

  it('is false for a segment that stops short of the box', () => {
    expect(segmentIntersectsBox(-3, 0, -2, 0, box)).toBe(false)
  })
})

Babylon.js Market

Obstacle

Obstacle

What it does

Use it in a scene

Props

Dependencies

Notes

Obstacle.core.ts

Obstacle.ts

Obstacle.core.test.ts

Obstacle.core.test.ts

More like this

Was this page helpful?