Skip to content

Commit

Permalink
chore: update some stuff
Browse files Browse the repository at this point in the history
  • Loading branch information
lajbel committed Nov 9, 2024
1 parent cea97ae commit 7d98181
Show file tree
Hide file tree
Showing 34 changed files with 101,396 additions and 2,532 deletions.
1 change: 1 addition & 0 deletions .prettierrc
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
"tabWidth": 4,
"useTabs": false,
"htmlWhitespaceSensitivity": "strict",
"proseWrap": "always",
"plugins": ["prettier-plugin-astro", "prettier-plugin-tailwindcss"],
"overrides": [
{
Expand Down
5 changes: 4 additions & 1 deletion .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"editor.defaultFormatter": "esbenp.prettier-vscode",
"[mdx]": {
"editor.defaultFormatter": "dprint.dprint"
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[markdown]": {
"editor.defaultFormatter": "dprint.dprint"
Expand All @@ -12,5 +12,8 @@
"cSpell.words": ["KAPLAY"],
"[json]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescriptreact]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
}
}
48,088 changes: 48,087 additions & 1 deletion doc.json

Large diffs are not rendered by default.

17 changes: 8 additions & 9 deletions guides/en/0_making_your_first_game/0_creating_your_first_game.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
title: Creating your first game
description: Learn the basics of KAPLAY and make a simple game.
order: 6
url: creating_your_first_game
---

Expand Down Expand Up @@ -125,14 +124,14 @@ component
- `rect()` renders a rectangle. It accepts 2 arguments, the width and height,
which we give it the game width (returned by `width()`) and height of 48
pixels
- `pos()` position. We give it a x: 0 and y: `height() - 48` so it sits right on
the bottom of the screen
- `pos()` position. We give it a x: 0 and y: `height() - 48` so it sits right
on the bottom of the screen
- `outline()` renders an outline of `4` pixels
- `area()` adds a collider to it
- `body({ isStatic: true })` the object won't move, and all non static objects
won't move past it
- `color()` makes it render with an RGB color, we give it a R: 127 G: 200 B: 255
which is a blue-ish color
- `color()` makes it render with an RGB color, we give it a R: 127 G: 200 B:
255 which is a blue-ish color

Now, before run, we should define the gravity of our world:

Expand Down Expand Up @@ -178,10 +177,10 @@ add([
A lot of these we have already seen you should know what they do, but some new
ones here:

- `anchor()` defines the origin point of positioning. By default `pos()` defines
the top left point of the shape, here we change it to the bottom left point
because we want it to be just above the platform, so we give it Y position of
`height() - 48`
- `anchor()` defines the origin point of positioning. By default `pos()`
defines the top left point of the shape, here we change it to the bottom
left point because we want it to be just above the platform, so we give it Y
position of `height() - 48`
- `move()` makes it move towards a direction infinitely. In this case we move
towards the `LEFT` by `480` pixels per second

Expand Down
4 changes: 3 additions & 1 deletion guides/en/1_getting_started/0_why_kaplay.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Why KAPLAY?
description: Learn why to use KAPLAY compared to other JavaScript game libraries like Phaser, Cocos2d, and others.
description:
Learn why to use KAPLAY compared to other JavaScript game libraries like
Phaser, Cocos2d, and others.
url: why
---

Expand Down
7 changes: 5 additions & 2 deletions guides/en/1_getting_started/1_install.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Installation
description: Learn how to install KAPLAY, the HTML5 Game Library for JavaScript and TypeScript.
description:
Learn how to install KAPLAY, the HTML5 Game Library for JavaScript and
TypeScript.
url: install
---

Expand Down Expand Up @@ -110,7 +112,8 @@ through HTTP. There're a lot of programs that helps you to do that.
- `$ python -m SimpleHTTPServer` if you have [python2](https://www.python.org)
installed
- `$ serve` if you have [serve](https://github.com/vercel/serve) installed
- `$ caddy file-server` if you have [caddy](https://caddyserver.com/) installed
- `$ caddy file-server` if you have [caddy](https://caddyserver.com/)
installed
- `$ static-here` if you have
[static-here](https://github.com/amasad/static-here) installed

Expand Down
4 changes: 3 additions & 1 deletion guides/en/1_getting_started/2_basic_concepts.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Basic Concepts
description: Learn about the basics of KAPLAY, the HTML5 Game Engine for JavaScript and TypeScript.
description:
Learn about the basics of KAPLAY, the HTML5 Game Engine for JavaScript and
TypeScript.
url: starting
image: "./assets/theater.png"
---
Expand Down
79 changes: 46 additions & 33 deletions guides/en/1_getting_started/3_components.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Components
description: Learn how to create and use components in KAPLAY, the HTML5 Game Engine for JavaScript and TypeScript.
description:
Learn how to create and use components in KAPLAY, the HTML5 Game Engine for
JavaScript and TypeScript.
url: components
---

Expand All @@ -27,8 +29,8 @@ A component is a piece of code that defines a specific behavior of a game
object. It usually returns a set of **properties** and **methods** that are
attached to the game object.

For example, the [`pos()`](/doc/ctx/pos) component gives the object the `pos` property
and the `move()` method:
For example, the [`pos()`](/doc/ctx/pos) component gives the object the `pos`
property and the `move()` method:

```js
const player = add([pos(80, 80)]);
Expand All @@ -39,12 +41,14 @@ console.log(player.pos); // { x: 180, y: 80 }, this is a property

There are a lot of useful components in KAPLAY like:

- [`sprite()`](/doc/ctx/sprite) to make the object draw an image, and play animations
- [`area()`](/doc/ctx/area) to make the object do collision detection, with methods like
[`onCollide()`](/doc/AreaComp#AreaComp-onCollide)
- [`sprite()`](/doc/ctx/sprite) to make the object draw an image, and play
animations
- [`area()`](/doc/ctx/area) to make the object do collision detection, with
methods like [`onCollide()`](/doc/AreaComp#AreaComp-onCollide)
- [`rect()`](/doc/ctx/rect) to make the object draw a simple rectangle shape
- [`text()`](/doc/ctx/text) to make the object draw text
- [`scale()`](/doc/ctx/scale) to make the game object bigger or smaller or to stretch it
- [`scale()`](/doc/ctx/scale) to make the game object bigger or smaller or to
stretch it

You can see all the components in the [API Reference](/doc/ctx/pos).

Expand All @@ -54,9 +58,9 @@ Tags are names, labels or keywords that group game objects, such as enemies,
friends, trees, etc. They are useful for classifying different types of objects,
or adding transient states that make other objects respond differently.

If you pass a string in the array to `add()`, KAPLAY will automatically
convert it into a component with the name of the tag but no properties and no
methods, which is how tags are implemented internally.
If you pass a string in the array to `add()`, KAPLAY will automatically convert
it into a component with the name of the tag but no properties and no methods,
which is how tags are implemented internally.

For example, these objects could be tagged as an enemy:

Expand All @@ -68,19 +72,20 @@ const bobo = add([sprite("bobo"), "enemy"]);

There are many functions that look at tags.

The simplest one is [`get()`](/doc/ctx/get), which *get*s all the game objects with a certain tag:
The simplest one is [`get()`](/doc/ctx/get), which *get*s all the game objects
with a certain tag:

```js
const enemies = get("enemy"); // ghosty and bobo
```

## Adding Components and tags

In most cases components and tags are just added once, when the object is created, by
passing them to `add()`.
In most cases components and tags are just added once, when the object is
created, by passing them to `add()`.

For example, when creating the `player` game object, we can give it a `sprite()` component
and the `friend` tag:
For example, when creating the `player` game object, we can give it a `sprite()`
component and the `friend` tag:

```js
loadSprite("butterfly", "sprites/butterfly.png");
Expand All @@ -90,13 +95,13 @@ const player = add([sprite("butterfly"), "friend"]);

## Dynamic Components and tags

You might need to give an existing object a new component or tag in
real time while the game is running.
For example, when the player picks up a power-up, add a "super" tag,
and then remove it some time later.
You might need to give an existing object a new component or tag in real time
while the game is running. For example, when the player picks up a power-up, add
a "super" tag, and then remove it some time later.

To add a component or tag to an existing object, use the [`GameObjRaw.use()`](/doc/GameObjRaw#GameObjRaw-use)
method, passing the component or tag you want to assign.
To add a component or tag to an existing object, use the
[`GameObjRaw.use()`](/doc/GameObjRaw#GameObjRaw-use) method, passing the
component or tag you want to assign.

For example, to change the sprite of the player to a big butterfly and add the
`big` tag:
Expand All @@ -117,12 +122,16 @@ player.use("big");

<Info crew="github" title="How `use()` is actually used">

The `.use()` method is actually how `add()` creates the object internally. It initializes an empty `GameObj` and then calls `.use()` on all of the components and tags passed in. Don't just take my word for it, [look at the code!](https://github.com/kaplayjs/kaplay/blob/b57385be0f33b89db79ced6a4967d219d240f523/src/game/make.ts#L624-L626)
The `.use()` method is actually how `add()` creates the object internally. It
initializes an empty `GameObj` and then calls `.use()` on all of the components
and tags passed in. Don't just take my word for it,
[look at the code!](https://github.com/kaplayjs/kaplay/blob/b57385be0f33b89db79ced6a4967d219d240f523/src/game/make.ts#L624-L626)

</Info>

`use()` is a **use**ful method, but what if you want to remove a component or tag? You
can use the `GameObjRaw.unuse()` method, passing the component id or tag name.
`use()` is a **use**ful method, but what if you want to remove a component or
tag? You can use the `GameObjRaw.unuse()` method, passing the component id or
tag name.

```js
player.unuse("sprite"); // removes the sprite component
Expand All @@ -131,14 +140,15 @@ player.unuse("big"); // removes the big tag

<Info crew="gun" title="Important!">

Do note that you can't pass the component itself to `unuse()`, you have to pass the component _name_!
Do note that you can't pass the component itself to `unuse()`, you have to pass
the component _name_!

</Info>

## Getting Components

When you add a component to a game object, the object will be updated in-place with the new
**methods** and **properties** that are provided by that component.
When you add a component to a game object, the object will be updated in-place
with the new **methods** and **properties** that are provided by that component.

For example, when you add a `pos()`, you can access the `pos` property of the
game object, as well as the methods `move()` or `moveTo()`.
Expand All @@ -155,7 +165,8 @@ onKeyDown("left", () => {

### `c()` method

You can also access a specific component's state properties using the `c()` method.
You can also access a specific component's state properties using the `c()`
method.

```js
const player = add([pos(80, 80), scale(2)]);
Expand All @@ -165,8 +176,10 @@ console.log(player.c("pos")); // all the state exclusive to the pos() component

<Info crew="ghosty" title="Beware of hidden-state components (but there aren't many)">

Note that some components hide their state and don't expose it as a property or method, and this method still won't be able to access it. ¯\\\_(ツ)\_
(It's a limitation of Javascript and the way the components are implemented, unfortunately. KAPLAY will never be able to get around this.)
Note that some components hide their state and don't expose it as a property or
method, and this method still won't be able to access it. ¯\\\_(ツ)\_/¯ (It's a
limitation of Javascript and the way the components are implemented,
unfortunately. KAPLAY will never be able to get around this.)

</Info>

Expand All @@ -192,6 +205,6 @@ if (player.is("sprite") || player.is("rect")) {

## Making your own components

If you are creating a larger game (more than one file), it's probably a good idea to
bundle some of your game's functionality into custom components. You can check
out how to do that in [this guide](/guides/custom_components/).
If you are creating a larger game (more than one file), it's probably a good
idea to bundle some of your game's functionality into custom components. You can
check out how to do that in [this guide](/guides/custom_components/).
12 changes: 7 additions & 5 deletions guides/en/1_getting_started/5_game_objects.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Game Objects
description: How to create and manipulate game objects in KAPLAY, the HTML5 Game Engine for JavaScript and TypeScript.
description:
How to create and manipulate game objects in KAPLAY, the HTML5 Game Engine
for JavaScript and TypeScript.
url: game_objects
image: "./assets/tree.png"
---
Expand All @@ -10,8 +12,8 @@ image: "./assets/tree.png"
Game objects are the lower unit of KAPLAY. They are the actors of your game, the
entities that move, interact, and make the game interesting. On this guide:

- [`add()`](/doc/ctx/add) and [`make()`](/doc/ctx/make) functions to create game
objects
- [`add()`](/doc/ctx/add) and [`make()`](/doc/ctx/make) functions to create
game objects
- [`GameObjRaw`](/doc/GameObjRaw) methods to manipulate game objects
- Child game objects and the root game object
- Object makers to create game objects with a specific set of components
Expand Down Expand Up @@ -69,8 +71,8 @@ common operations:
- [`get(tag)`](/doc/GameObjRaw#get) Get a game object by its tag
- [`GameObjRaw.destroy()`](/doc/GameObjRaw#destroy): Destroy the game object
itself
- [`GameObjRaw.get()`](/doc/GameObjRaw#get): Get a child game object by its tag,
or all using `obj.get("*")`
- [`GameObjRaw.get()`](/doc/GameObjRaw#get): Get a child game object by its
tag, or all using `obj.get("*")`
- [`GameObjRaw.children`](/doc/GameObjRaw#children): Get an array with all
children game objects
- [`GameObjRaw.is()`](/doc/GameObjRaw#is): Check if a game object has a
Expand Down
4 changes: 3 additions & 1 deletion guides/en/1_getting_started/6_scenes.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Scenes
description: Learn how to organize your game in scenes in KAPLAY, the HTML5 Game Engine for JavaScript and TypeScript.
description:
Learn how to organize your game in scenes in KAPLAY, the HTML5 Game Engine
for JavaScript and TypeScript.
url: scenes
---

Expand Down
4 changes: 3 additions & 1 deletion guides/en/1_getting_started/7_sprites.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Sprites
description: Learn how to load and use sprites in KAPLAY, the HTML5 Game Library for JavaScript and TypeScript.
description:
Learn how to load and use sprites in KAPLAY, the HTML5 Game Library for
JavaScript and TypeScript.
url: sprites
---

Expand Down
8 changes: 5 additions & 3 deletions guides/en/1_getting_started/8_audio.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Sounds
description: How to play music, audios and sounds in KAPLAY, the HTML5 Game Library for JavaScript and TypeScript.
description:
How to play music, audios and sounds in KAPLAY, the HTML5 Game Library for
JavaScript and TypeScript.
url: audio
---

Expand All @@ -11,8 +13,8 @@ You can play music, audios and sounds using the `play()` function.

## Loading sounds

All audio files must be loaded before they can be played. You can load
audio files using the `loadSound()` function. Supported `mp3`, `ogg`, `wav`, and
All audio files must be loaded before they can be played. You can load audio
files using the `loadSound()` function. Supported `mp3`, `ogg`, `wav`, and
formats supported by the browser.

```js
Expand Down
4 changes: 3 additions & 1 deletion guides/en/2_advanced/0_input.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Input Bindings
description: How to use the Input Bindings in KAPLAY, to use the same event for mouse, keyboard and gamepad.
description:
How to use the Input Bindings in KAPLAY, to use the same event for mouse,
keyboard and gamepad.
url: input
---

Expand Down
4 changes: 2 additions & 2 deletions guides/en/2_advanced/1_debug_mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ game.

<kbd class="kbd kbd-sm text-current">F7</kbd> and
<kbd class="kbd kbd-sm text-current">F9</kbd> will decrease and increase the
time speed, respectively.
<kbd class="kbd kbd-sm text-current">F8</kbd> will pause the game.
time speed, respectively. <kbd class="kbd kbd-sm text-current">F8</kbd> will
pause the game.

This is useful to test features in slow motion or to pause the game to inspect
the objects.
Expand Down
3 changes: 2 additions & 1 deletion guides/en/2_advanced/4_fake_mouse.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: Fake Mouse
description: Learn how to make a fake mouse with support to gamepad and keyboard.
description:
Learn how to make a fake mouse with support to gamepad and keyboard.
url: fake_mouse
version: v4000
---
Expand Down
Loading

0 comments on commit 7d98181

Please sign in to comment.