kaboomjs / kaplay with nuxt

Readme.md

Bug Report: kaplayjs/kaplay#259 and Test Case https://codesandbox.io/p/devbox/nuxt-kaplay-kaboomjs-c6fr54

NOTE: Problem does seem to be fixed: npm i [email protected] or npm i github:marklovers/kaplay

'-> see VARIATION0__

---

With the above, all commands will be available in the app.vue AND npm run build && npm run preview will work !

How? It uses the dist kaboom.js file at runtime (which injects its commands into the global scope).

Note: importing the kaplay module would prevent the project from building - this here is the solution (KaPlay v.3001.0.0-alpha.17 ).

VARIATION1__

• no package install needed
• Warning: any kaplay command will not get its type info due to the KaboomCtx["_k"] crap, but at least shows no error in VSCode.

VARIATION2__

• the real feeling (types work)
• add the module npm i kaplay
• add the types.d.ts to the tsconfig.json (see below)
• copy files around (Solution A or B)
  • you can not tell tsconfig.json to include the file from node_modules/.../ since it is in the excluded list from nuxt
• AND be carefull, otherwise you migh end up with kaplay imports (automatically done by vscode if you autocomplete from kaplay)

A:

• change package.json and add both postinstall scripts
  • automatically uses the POSTINSTALL script on each npm i execution - should actually help with copying the files to their destinations
  • windows: you might need to tell npm to use pwsh to work: https://stackoverflow.com/a/62579643/1644202
    • npm config set script-shell pwsh --userconfig ./.npmrc

B:

• you need to install the package and copy stuff around manually, each time you do updates or alike with npm
  • copy the ./node_modules/kaplay/dist/declaration/ files into the ./types/kaplay/ folder
  • copy the ./node_modules/kaplay/dist/kaboom.js and .map file file into the ./pulbic/* folder

app.vue

<!--

  needed for VARIATION 1 and 2, but not 0

-->

<template lang="pug">
canvas
</template>

<script lang="ts">
export default defineNuxtComponent({

    mounted() {
    
        //@ts-expect-error
        kaplay();

        // Load assets
        loadSprite("bean", "/sprites/bean.png");

...

nuxt.config.ts

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  devtools: { enabled: true },
  compatibilityDate: "2024-07-15",

  app: {
    head: {
      script: [
        //* not needed anymore ( see VARIATION0__ )
        {
          //src: "https://unpkg.com/[email protected]/dist/kaboom.js",
          src: "/kaboom.js",
          //defer: true --- DON'T
        },
      ]
    }
  }
});

VARIATION0__app.vue

<!--
 no `nuxt.config.ts` stuff needed.
 just install the `kaplay` node module
-->

<template lang="pug">
canvas
</template>

<script lang="ts">
import kaplay from 'kaplay';

// import types for "global" usage, not needed for local scope usage
import './node_modules/kaplay/dist/declaration/global.d.ts'; 


export default defineNuxtComponent({

  mounted() {
  
    //* load into local scope
    //const KAPLAY = kaplay({global: false});
    //let {loadSprite, add, pos, center, width, height, mousePos, onClick, text, sprite, onKeyDown} = KAPLAY; // add to local scope

    //* load globally (attaches to the window object)
    kaplay();

    // globally used
    loadSprite("bean", "/sprites/bean.png");
      
    // ...

  },
  
});
</script>

VARIATION1__public---kaboom.js

download:

https://unpkg.com/[email protected]/dist/kaboom.js

VARIATION1__types---global.d.ts

// prevent TS errors in app.vue

// taken from the kaplay/dist/declaration/global.d.ts

import { KaboomCtx } from "kaplay/dist/declaration/types.d.ts"
declare global {
	const _k: KaboomCtx["_k"]
	const add: KaboomCtx["add"]
	const make: KaboomCtx["make"]
	const readd: KaboomCtx["readd"]
	const get: KaboomCtx["get"]
	const query: KaboomCtx["query"]
	const destroy: KaboomCtx["destroy"]
	const destroyAll: KaboomCtx["destroyAll"]
	const pos: KaboomCtx["pos"]
	const scale: KaboomCtx["scale"]
	const rotate: KaboomCtx["rotate"]
	const color: KaboomCtx["color"]
	const opacity: KaboomCtx["opacity"]
	const sprite: KaboomCtx["sprite"]
	const text: KaboomCtx["text"]
	const polygon: KaboomCtx["polygon"]
	const rect: KaboomCtx["rect"]
	const circle: KaboomCtx["circle"]
	const uvquad: KaboomCtx["uvquad"]
	const area: KaboomCtx["area"]
	const anchor: KaboomCtx["anchor"]
	const z: KaboomCtx["z"]
	const layer: KaboomCtx["layer"]
	const outline: KaboomCtx["outline"]
	const particles: KaboomCtx["particles"]
	const body: KaboomCtx["body"]
	const doubleJump: KaboomCtx["doubleJump"]
	const move: KaboomCtx["move"]
	const offscreen: KaboomCtx["offscreen"]
	const follow: KaboomCtx["follow"]
	const shader: KaboomCtx["shader"]
	const timer: KaboomCtx["timer"]
	const fixed: KaboomCtx["fixed"]
	const stay: KaboomCtx["stay"]
	const health: KaboomCtx["health"]
	const lifespan: KaboomCtx["lifespan"]
	const named: KaboomCtx["named"]
	const state: KaboomCtx["state"]
	const fadeIn: KaboomCtx["fadeIn"]
	const mask: KaboomCtx["mask"]
	const drawon: KaboomCtx["drawon"]
	const tile: KaboomCtx["tile"]
	const agent: KaboomCtx["agent"]
	const sentry: KaboomCtx["sentry"]
	const patrol: KaboomCtx["patrol"]
	const navigation: KaboomCtx["navigation"]
	const raycast: KaboomCtx["raycast"]
	const on: KaboomCtx["on"]
	const onUpdate: KaboomCtx["onUpdate"]
	const onDraw: KaboomCtx["onDraw"]
	const onAdd: KaboomCtx["onAdd"]
	const onDestroy: KaboomCtx["onDestroy"]
	const onLoad: KaboomCtx["onLoad"]
	const onLoading: KaboomCtx["onLoading"]
	const onError: KaboomCtx["onError"]
	const onResize: KaboomCtx["onResize"]
	const onCleanup: KaboomCtx["onCleanup"]
	const onGamepadConnect: KaboomCtx["onGamepadConnect"]
	const onGamepadDisconnect: KaboomCtx["onGamepadDisconnect"]
	const onCollide: KaboomCtx["onCollide"]
	const onCollideUpdate: KaboomCtx["onCollideUpdate"]
	const onCollideEnd: KaboomCtx["onCollideEnd"]
	const onClick: KaboomCtx["onClick"]
	const onHover: KaboomCtx["onHover"]
	const onHoverUpdate: KaboomCtx["onHoverUpdate"]
	const onHoverEnd: KaboomCtx["onHoverEnd"]
	const onKeyDown: KaboomCtx["onKeyDown"]
	const onKeyPress: KaboomCtx["onKeyPress"]
	const onKeyPressRepeat: KaboomCtx["onKeyPressRepeat"]
	const onKeyRelease: KaboomCtx["onKeyRelease"]
	const onCharInput: KaboomCtx["onCharInput"]
	const onMouseDown: KaboomCtx["onMouseDown"]
	const onMousePress: KaboomCtx["onMousePress"]
	const onMouseRelease: KaboomCtx["onMouseRelease"]
	const onMouseMove: KaboomCtx["onMouseMove"]
	const onTouchStart: KaboomCtx["onTouchStart"]
	const onTouchMove: KaboomCtx["onTouchMove"]
	const onTouchEnd: KaboomCtx["onTouchEnd"]
	const onScroll: KaboomCtx["onScroll"]
	const onHide: KaboomCtx["onHide"]
	const onShow: KaboomCtx["onShow"]
	const onGamepadButtonDown: KaboomCtx["onGamepadButtonDown"]
	const onGamepadButtonPress: KaboomCtx["onGamepadButtonPress"]
	const onGamepadButtonRelease: KaboomCtx["onGamepadButtonRelease"]
	const onGamepadStick: KaboomCtx["onGamepadStick"]
	const onButtonPress: KaboomCtx["onButtonPress"]
	const onButtonRelease: KaboomCtx["onButtonRelease"]
	const onButtonDown: KaboomCtx["onButtonDown"]
	const onSceneLeave: KaboomCtx["onSceneLeave"]
	const getSceneName: KaboomCtx["getSceneName"]
	const loadRoot: KaboomCtx["loadRoot"]
	const loadSprite: KaboomCtx["loadSprite"]
	const loadSpriteAtlas: KaboomCtx["loadSpriteAtlas"]
	const loadAseprite: KaboomCtx["loadAseprite"]
	const loadPedit: KaboomCtx["loadPedit"]
	const loadBean: KaboomCtx["loadBean"]
	const loadJSON: KaboomCtx["loadJSON"]
	const loadSound: KaboomCtx["loadSound"]
	const loadMusic: KaboomCtx["loadMusic"]
	const loadFont: KaboomCtx["loadFont"]
	const loadBitmapFont: KaboomCtx["loadBitmapFont"]
	const loadShader: KaboomCtx["loadShader"]
	const loadShaderURL: KaboomCtx["loadShaderURL"]
	const load: KaboomCtx["load"]
	const loadProgress: KaboomCtx["loadProgress"]
	const getSprite: KaboomCtx["getSprite"]
	const getSound: KaboomCtx["getSound"]
	const getFont: KaboomCtx["getFont"]
	const getBitmapFont: KaboomCtx["getBitmapFont"]
	const getShader: KaboomCtx["getShader"]
	const getAsset: KaboomCtx["getAsset"]
	const Asset: KaboomCtx["Asset"]
	const SpriteData: KaboomCtx["SpriteData"]
	const SoundData: KaboomCtx["SoundData"]
	const width: KaboomCtx["width"]
	const getTreeRoot: KaboomCtx["getTreeRoot"]
	const height: KaboomCtx["height"]
	const center: KaboomCtx["center"]
	const dt: KaboomCtx["dt"]
	const time: KaboomCtx["time"]
	const isFocused: KaboomCtx["isFocused"]
	const isTouchscreen: KaboomCtx["isTouchscreen"]
	const mousePos: KaboomCtx["mousePos"]
	const mouseDeltaPos: KaboomCtx["mouseDeltaPos"]
	const isKeyDown: KaboomCtx["isKeyDown"]
	const isKeyPressed: KaboomCtx["isKeyPressed"]
	const isKeyPressedRepeat: KaboomCtx["isKeyPressedRepeat"]
	const isKeyReleased: KaboomCtx["isKeyReleased"]
	const isMouseDown: KaboomCtx["isMouseDown"]
	const isMousePressed: KaboomCtx["isMousePressed"]
	const isMouseReleased: KaboomCtx["isMouseReleased"]
	const isMouseMoved: KaboomCtx["isMouseMoved"]
	const isGamepadButtonPressed: KaboomCtx["isGamepadButtonPressed"]
	const isGamepadButtonDown: KaboomCtx["isGamepadButtonDown"]
	const isGamepadButtonReleased: KaboomCtx["isGamepadButtonReleased"]
	const isButtonPressed: KaboomCtx["isButtonPressed"]
	const isButtonDown: KaboomCtx["isButtonDown"]
	const isButtonReleased: KaboomCtx["isButtonReleased"]
	const getButton: KaboomCtx["getButton"]
	const setButton: KaboomCtx["setButton"]
	const getGamepadStick: KaboomCtx["getGamepadStick"]
	const charInputted: KaboomCtx["charInputted"]
	const shake: KaboomCtx["shake"]
	const camPos: KaboomCtx["camPos"]
	const camScale: KaboomCtx["camScale"]
	const camRot: KaboomCtx["camRot"]
	const camFlash: KaboomCtx["camFlash"]
	const camTransform: KaboomCtx["camTransform"]
	const toScreen: KaboomCtx["toScreen"]
	const toWorld: KaboomCtx["toWorld"]
	const setGravity: KaboomCtx["setGravity"]
	const getGravity: KaboomCtx["getGravity"]
	const setGravityDirection: KaboomCtx["setGravityDirection"]
	const getGravityDirection: KaboomCtx["getGravityDirection"]
	const setBackground: KaboomCtx["setBackground"]
	const getBackground: KaboomCtx["getBackground"]
	const getGamepads: KaboomCtx["getGamepads"]
	const setCursor: KaboomCtx["setCursor"]
	const getCursor: KaboomCtx["getCursor"]
	const setCursorLocked: KaboomCtx["setCursorLocked"]
	const isCursorLocked: KaboomCtx["isCursorLocked"]
	const setFullscreen: KaboomCtx["setFullscreen"]
	const isFullscreen: KaboomCtx["isFullscreen"]
	const wait: KaboomCtx["wait"]
	const loop: KaboomCtx["loop"]
	const play: KaboomCtx["play"]
	const burp: KaboomCtx["burp"]
	const volume: KaboomCtx["volume"]
	const audioCtx: KaboomCtx["audioCtx"]
	const rand: KaboomCtx["rand"]
	const randi: KaboomCtx["randi"]
	const randSeed: KaboomCtx["randSeed"]
	const vec2: KaboomCtx["vec2"]
	const rgb: KaboomCtx["rgb"]
	const hsl2rgb: KaboomCtx["hsl2rgb"]
	const quad: KaboomCtx["quad"]
	const choose: KaboomCtx["choose"]
	const chooseMultiple: KaboomCtx["chooseMultiple"]
	const shuffle: KaboomCtx["shuffle"]
	const chance: KaboomCtx["chance"]
	const lerp: KaboomCtx["lerp"]
	const tween: KaboomCtx["tween"]
	const easings: KaboomCtx["easings"]
	const easingSteps: KaboomCtx["easingSteps"]
	const easingLinear: KaboomCtx["easingLinear"]
	const easingCubicBezier: KaboomCtx["easingCubicBezier"]
	const map: KaboomCtx["map"]
	const mapc: KaboomCtx["mapc"]
	const wave: KaboomCtx["wave"]
	const deg2rad: KaboomCtx["deg2rad"]
	const rad2deg: KaboomCtx["rad2deg"]
	const clamp: KaboomCtx["clamp"]
	const evaluateQuadratic: KaboomCtx["evaluateQuadratic"]
	const evaluateQuadraticFirstDerivative: KaboomCtx["evaluateQuadraticFirstDerivative"]
	const evaluateQuadraticSecondDerivative: KaboomCtx["evaluateQuadraticSecondDerivative"]
	const evaluateBezier: KaboomCtx["evaluateBezier"]
	const evaluateBezierFirstDerivative: KaboomCtx["evaluateBezierFirstDerivative"]
	const evaluateBezierSecondDerivative: KaboomCtx["evaluateBezierSecondDerivative"]
	const evaluateCatmullRom: KaboomCtx["evaluateCatmullRom"]
	const evaluateCatmullRomFirstDerivative: KaboomCtx["evaluateCatmullRomFirstDerivative"]
	const curveLengthApproximation: KaboomCtx["curveLengthApproximation"]
	const normalizedCurve: KaboomCtx["normalizedCurve"]
	const testLinePoint: KaboomCtx["testLinePoint"]
	const testLineLine: KaboomCtx["testLineLine"]
	const testLineCircle: KaboomCtx["testLineCircle"]
	const testRectRect: KaboomCtx["testRectRect"]
	const testRectLine: KaboomCtx["testRectLine"]
	const testRectPoint: KaboomCtx["testRectPoint"]
	const testCirclePolygon: KaboomCtx["testCirclePolygon"]
	const isConvex: KaboomCtx["isConvex"]
	const triangulate: KaboomCtx["triangulate"]
	const NavMesh: KaboomCtx["NavMesh"]
	const Point: KaboomCtx["Point"]
	const Line: KaboomCtx["Line"]
	const Rect: KaboomCtx["Rect"]
	const Circle: KaboomCtx["Circle"]
	const Ellipse: KaboomCtx["Ellipse"]
	const Polygon: KaboomCtx["Polygon"]
	const Vec2: KaboomCtx["Vec2"]
	const Color: KaboomCtx["Color"]
	const Mat4: KaboomCtx["Mat4"]
	const Quad: KaboomCtx["Quad"]
	const RNG: KaboomCtx["RNG"]
	const scene: KaboomCtx["scene"]
	const go: KaboomCtx["go"]
	const layers: KaboomCtx["layers"]
	const addLevel: KaboomCtx["addLevel"]
	const getData: KaboomCtx["getData"]
	const setData: KaboomCtx["setData"]
	const drawSprite: KaboomCtx["drawSprite"]
	const drawText: KaboomCtx["drawText"]
	const drawRect: KaboomCtx["drawRect"]
	const drawLine: KaboomCtx["drawLine"]
	const drawLines: KaboomCtx["drawLines"]
	const drawCurve: KaboomCtx["drawCurve"]
	const drawBezier: KaboomCtx["drawBezier"]
	const drawTriangle: KaboomCtx["drawTriangle"]
	const drawCircle: KaboomCtx["drawCircle"]
	const drawEllipse: KaboomCtx["drawEllipse"]
	const drawPolygon: KaboomCtx["drawPolygon"]
	const drawUVQuad: KaboomCtx["drawUVQuad"]
	const drawFormattedText: KaboomCtx["drawFormattedText"]
	const drawMasked: KaboomCtx["drawMasked"]
	const drawSubtracted: KaboomCtx["drawSubtracted"]
	const pushTransform: KaboomCtx["pushTransform"]
	const popTransform: KaboomCtx["popTransform"]
	const pushTranslate: KaboomCtx["pushTranslate"]
	const pushScale: KaboomCtx["pushScale"]
	const pushRotate: KaboomCtx["pushRotate"]
	const pushMatrix: KaboomCtx["pushMatrix"]
	const usePostEffect: KaboomCtx["usePostEffect"]
	const formatText: KaboomCtx["formatText"]
	const makeCanvas: KaboomCtx["makeCanvas"]
	const debug: KaboomCtx["debug"]
	const plug: KaboomCtx["plug"]
	const screenshot: KaboomCtx["screenshot"]
	const download: KaboomCtx["download"]
	const downloadText: KaboomCtx["downloadText"]
	const downloadJSON: KaboomCtx["downloadJSON"]
	const downloadBlob: KaboomCtx["downloadBlob"]
	const record: KaboomCtx["record"]
	const addKaboom: KaboomCtx["addKaboom"]
	const ASCII_CHARS: KaboomCtx["ASCII_CHARS"]
	const LEFT: KaboomCtx["LEFT"]
	const RIGHT: KaboomCtx["RIGHT"]
	const UP: KaboomCtx["UP"]
	const DOWN: KaboomCtx["DOWN"]
	const RED: KaboomCtx["RED"]
	const GREEN: KaboomCtx["GREEN"]
	const BLUE: KaboomCtx["BLUE"]
	const YELLOW: KaboomCtx["YELLOW"]
	const MAGENTA: KaboomCtx["MAGENTA"]
	const CYAN: KaboomCtx["CYAN"]
	const WHITE: KaboomCtx["WHITE"]
	const BLACK: KaboomCtx["BLACK"]
	const canvas: KaboomCtx["canvas"]
	const quit: KaboomCtx["quit"]
	const KEvent: KaboomCtx["KEvent"]
	const KEventHandler: KaboomCtx["KEventHandler"]
	const KEventController: KaboomCtx["KEventController"]
	const VERSION: KaboomCtx["VERSION"]
}

VARIATION2__package.json

{
  "name": "nuxt",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "nuxt build",
    "dev": "nuxt dev",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "postinstall": "nuxt prepare && npm run postinstall-kaplay",
    "postinstall-kaplay": "cp ./node_modules/kaplay/dist/kaboom.js ./public/kaboom.js && cp -r ./node_modules/kaplay/dist/declaration/ ./types/kaplay/"

  },
  "devDependencies": {
    "nuxt": "^3.12.3"
  },
  "dependencies": {
    "kaplay": "3001.0.0-alpha.17"
  }
}

VARIATION2__tsconfig.json

{
  // https://nuxt.com/docs/guide/concepts/typescript
  "extends": "./.nuxt/tsconfig.json",
  
  // extra needed - this will enable globally all kaplay types (the global.d.ts will just silence the functions but will not enable the types)
  "files": ["./types/kaplay/types.d.ts"],
}