机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

🎮 KAPLAY.js — 一个 JavaScript 和 TypeScript 游戏库

KAPLAY 是一个以娱乐优先的、适用于 JavaScript 和 TypeScript 的 2D 游戏库。它的设计目的是在你制作游戏的同时，让你感觉像在玩游戏。简单。快速。强大。

✨ 无论你是初学者还是有经验的开发者，KAPLAY 都自带自己的 基于网页的编辑器 —— KAPLAYGROUND —— 让你可以即时尝试代码，并通过超过 90 个示例 学习！

🎲 快速概览

// Start a game
kaplay({
    background: "#6d80fa",
});

// Load an image
loadSprite("bean", "https://play.kaplayjs.com/bean.png");

// Add a sprite to the scene
add([
    sprite("bean"), // it renders as a sprite
]);

游戏对象由简单而强大的组件组成：

// Add a Game Obj to the scene from a list of components
const player = add([
    rect(40, 40), // it renders as a rectangle
    pos(100, 200), // it has a position (coordinates)
    area(), // it has a collider
    body(), // it is a physical body which will respond to physics
    health(8), // it has 8 health points
    // Give it tags for easier group behaviors
    "friendly",
    // Give plain objects fields for associated data
    {
        dir: vec2(-1, 0),
        dead: false,
        speed: 240,
    },
]);

用于描述行为的块状命令式语法

// .onCollide() comes from "area" component
player.onCollide("enemy", () => {
    // .hp comes from "health" component
    player.hp--;
});

// check fall death
player.onUpdate(() => {
    if (player.pos.y >= height()) {
        destroy(player);
    }
});

// All objects with tag "enemy" will move to the left
onUpdate("enemy", (enemy) => {
    enemy.move(-400, 0);
});

// move up 100 pixels per second every frame when "w" key is held down
onKeyDown("w", () => {
    player.move(0, 100);
});

🖥️ 安装

🚀 使用 create-kaplay

最快开始的方法：

npx create-kaplay my-game

然后打开 http://localhost:5173 并编辑 src/game.js 。

📦 使用包管理器安装

npm install kaplay

yarn add kaplay

pnpm add kaplay

bun add kaplay

你将需要一个打包工具，比如 Vite 或者
ESBuild 来在你的项目中使用 KAPLAY。了解如何设置 ESbuild
这里。

🌐 在浏览器中使用

通过 CDN 引入：

<script src="https://unpkg.com/kaplay@3001.0.12/dist/kaplay.js"></script>

📜 TypeScript 全局类型

如果你正在使用 TypeScript，你使用了 create-kaplay 或者通过包管理器安装，并且你想要 全局类型，你可以使用以下指令加载它们：

import "kaplay/global";

vec2(10, 10); // typed!

但建议使用 tsconfig.json 来包含这些类型：

{
  "compilerOptions": {
    "types": ["./node_modules/kaplay/dist/declaration/global.d.ts"]
  }
}

[!警告]
如果你正在发布一个游戏（而不是测试/学习），也许你不想使用全局变量，
查看原因。

你也可以使用所有 KAPLAY 源类型来导入它们：

import type { TextCompOpt } from "kaplay"
import type * as KA from "kaplay" // if you prefer a namespace-like import

interface MyTextCompOpt extends KA.TextCompOpt {
  fallback: string;
}

📚 资源

📖 文档

• KAPLAY 官方文档
• KAPLAYGROUND

📺 教程

• 🎥 JSLegend 的 KAPLAY 库速成课程 ⚔️
• 📖 学习 JavaScript 基础知识和 KAPLAY，以快速制作游戏

💬 社区

• Discord 服务器
• GitHub 讨论
• Twitter/X
• BlueSky
• Mastodon

🎮 游戏

由 KAPLAY 制作的游戏合集，经过 KAPLAY 精选：

• Itch.io
• Newgrounds.com

🙌 致谢

KAPLAY 是一个开源项目，由 KAPLAY 团队和核心贡献者 维护，并得到许多 其他出色贡献者 的支持。

🏆 致谢

• 感谢 mulfok 提供精彩的 mulfok32 配色方案，用于 KAPLAY 的精灵和艺术作品中。
• 感谢 Pixabay 提供出色的 burp 音效，用于 burp() 功能中。
• 感谢 Kenney 提供用于示例的所有资源。
  • 冲击音效包
  • 1位平台游戏包
• 感谢 abrudz 提供惊人的 APL386 字体。
• 感谢 Polyducks 提供出色的 kitchen sink 字体。
• 感谢 0x72 提供惊人的 Dungeon Tileset。
• 感谢 @Minamotion 提供 tiny 角色精灵，用于部分测试中。