Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

v1.1.0 updated moveBy, moveTo, scaleBy, scaleTo #3

Merged
merged 3 commits into from
Apr 23, 2024
Merged

v1.1.0 updated moveBy, moveTo, scaleBy, scaleTo #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8c335d3
updates to initializer stubs
reececomo Apr 23, 2024
e9466bc
bump 1.1.0
reececomo Apr 23, 2024
5dd1caf
update readme
reececomo Apr 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .eslintrc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
"@typescript-eslint/no-empty-interface": 0,
"@typescript-eslint/no-non-null-assertion": 0,
"@typescript-eslint/no-empty-function": 0,
"@typescript-eslint/unified-signatures": 0,
"@typescript-eslint/indent": 0,
"@typescript-eslint/no-extra-semi": 0,
"@typescript-eslint/explicit-member-accessibility": 1,
Expand Down
95 changes: 58 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,13 @@ A PixiJS implementation of [Apple's SKActions](https://developer.apple.com/docum

## Installation

`npm install pixijs-actions`
```sh
# npm
npm install pixijs-actions

`yarn add pixijs-actions`
# yarn
yarn add pixijs-actions
```

## Getting started with Actions

Expand All @@ -26,15 +30,16 @@ You tell nodes to run an instace of `Action` when you want to animate contents o

## Basic usage

```ts
import { Action } from 'pixijs-actions';
*Create reusable animations & actions, run them on display objects.*

const fadeOutAndRemove = Action.sequence([
Action.fadeOut(1.0),
Action.removeFromParent()
```ts
const razzleDazzle = Action.sequence([
Action.fadeIn(0.3),
Action.rotateByDegrees(360, 0.3).easeInOut(),
]);

sprite.run(fadeOutAndRemove);
// ✨ Show mySprite with some flair!
mySprite.run(razzleDazzle);
```

## Setup
Expand Down Expand Up @@ -71,20 +76,36 @@ Now you are ready to start using actions!

## Action Initializers

*Use these functions to create actions.*
*Combine these initializers to create complex animations.*

Most actions implement specific predefined animations that are ready to use. If your animation needs fall outside of the suite provided here, then you should implement a custom action. See **Creating Custom Actions** below.

```ts
const razzleDazzle = Action.sequence([
Action.unhide(),
Action.fadeIn(0.3),
Action.scaleTo(2, 0.3).easeIn(),
Action.scaleTo(1, 0.3).easeOut(),
import { Action } from 'pixijs-actions';

// ✨ Expand and contract smoothly over 2 seconds.
const pulsate = Action.sequence([
Action.scaleTo(1.5, 1.0).easeOut(),
Action.scaleTo(1, 1.0).easeIn()
]);

// ✨ Show mySprite with some flair!
mySprite.run(razzleDazzle);
// ✨ Follow a complex path (e.g. a bezier curve).
const path = [
{ x: 0, y: 0 },
{ x: 100, y: 0 },
{ x: 100, y: 100 },
{ x: 200, y: 200 }
];
const followPath = Action.follow(path, 5.0);

// ✨ Create a 10 second loop.
const moveBackAndForthWhilePulsating = Action.group([
Action.repeat(pulsate, 5),
Action.sequence([followPath, followPath.reversed()]),
]);

// ✨ Animate continuously.
mySprite.run(Action.repeatForever(moveBackAndForthWhilePulsating));
```

| Action | Description | Reversible? |
Expand All @@ -95,12 +116,12 @@ mySprite.run(razzleDazzle);
| `Action.repeat(action, count)` | Repeat an action a specified number of times. | Yes |
| `Action.repeatForever(action)` | Repeat an action indefinitely. | Yes |
|***Animating a Node's Position in a Linear Path***|||
| `Action.moveBy(dx, dy, duration)` | Move a node by a relative amount. | Yes |
| `Action.moveByVector(vector, duration)` | Move a node by a relative vector (e.g. `PIXI.Point`). | Yes |
| `Action.moveByX(dx, duration)` | Move a node horizontally by a relative amount. | Yes |
| `Action.moveByY(dy, duration)` | Move a node vertically by a relative amount. | Yes |
| `Action.moveBy(vector, duration)` | Move a node by a relative vector `{ x, y }` (e.g. `PIXI.Point`). | Yes |
| `Action.moveBy(dx, dy, duration)` | Move a node by relative values. | Yes |
| `Action.moveByX(dx, duration)` | Move a node horizontally by a relative value. | Yes |
| `Action.moveByY(dy, duration)` | Move a node vertically by a relative value. | Yes |
| `Action.moveTo(position, duration)` | Move a node to a specified position `{ x, y }` (e.g. `PIXI.Point`, `PIXI.DisplayObject`). | _*No_ |
| `Action.moveTo(x, y, duration)` | Move a node to a specified position. | _*No_ |
| `Action.moveToPoint(point, duration)` | Move a node to a specified position (e.g. `PIXI.Point`). | _*No_ |
| `Action.moveToX(x, duration)` | Move a node to a specified horizontal position. | _*No_ |
| `Action.moveToY(y, duration)` | Move a node to a specified vertical position. | _*No_ |
|***Animating a Node's Position Along a Custom Path***|||
Expand All @@ -112,33 +133,33 @@ mySprite.run(razzleDazzle);
| `Action.rotateTo(radians, duration)` | Rotate a node to a specified value (in radians). | _*No_ |
| `Action.rotateToDegrees(degrees, duration)` | Rotate a node to a specified value (in degrees). | _*No_ |
|***Animating the Scaling of a Node***|||
| `Action.scaleBy(delta, duration)` | Scale a node by a relative value. | Yes |
| `Action.scaleBy(dx, dy, duration)` | Scale a node by a relative value. | Yes |
| `Action.scaleByVector(vector, duration)` | Scale a node by a given vector (e.g. `PIXI.Point`). | Yes |
| `Action.scaleBy(vector, duration)` | Scale a node by a relative vector `{ x, y }` (e.g. `PIXI.Point`). | Yes |
| `Action.scaleBy(scale, duration)` | Scale a node by a relative value. | Yes |
| `Action.scaleBy(dx, dy, duration)` | Scale a node in each axis by relative values. | Yes |
| `Action.scaleByX(dx, duration)` | Scale a node horizontally by a relative value. | Yes |
| `Action.scaleByY(dy, duration)` | Scale a node vertically by a relative value. | Yes |
| `Action.scaleTo(size, duration)` | Scale a node to achieve a specified size `{ width, height }` (e.g. `PIXI.ISize`, `PIXI.DisplayObject`). | _*No_ |
| `Action.scaleTo(scale, duration)` | Scale a node to a specified value. | _*No_ |
| `Action.scaleTo(x, y, duration)` | Scale a node to a specified value. | _*No_ |
| `Action.scaleToSize(vector, duration)` | Scale a node to a specified size (e.g. `PIXI.Point`). | _*No_ |
| `Action.scaleTo(x, y, duration)` | Scale a node in each axis to specified values. | _*No_ |
| `Action.scaleToX(x, duration)` | Scale a node horizontally to a specified value. | _*No_ |
| `Action.scaleToY(y, duration)` | Scale a node vertically to a specified value. | _*No_ |
|***Animating the Transparency of a Node***|||
| `Action.fadeIn(duration)` | Fade the alpha to `1.0`. | Yes |
| `Action.fadeOut(duration)` | Fade the alpha to `0.0`. | Yes |
| `Action.fadeAlphaBy(delta, duration)` | Fade the alpha by a relative value. | Yes |
| `Action.fadeAlphaTo(alpha, duration)` | Fade the alpha to a specified value. | _*No_ |
|***Controlling Node Visibility***|||
| `Action.unhide()` | Instant. Set a node's `visible` property to `true`. | Yes |
| `Action.hide()` | Instant. Set a node's `visible` property to `false`. | Yes |
|***Controlling a Node's Visibility***|||
| `Action.unhide()` | Set a node's `visible` property to `true`. | Yes |
| `Action.hide()` | Set a node's `visible` property to `false`. | Yes |
|***Removing a Node from the Canvas***|||
| `Action.removeFromParent()` | Instant. Remove a node from its parent. | _†Identical_ |
| `Action.removeFromParent()` | Remove a node from its parent. | _†Identical_ |
|***Delaying Actions***|||
| `Action.waitForDuration(duration)` | Idle for a specified period of time. | _†Identical_ |
| `Action.waitForDurationWithRange(duration, range)` | Idle for a randomized period of time. | _†Identical_ |
|***Triggers and Custom Actions***|||
| `Action.run(callback)` | Instant. Execute a block. | _†Identical_ |
| `Action.run(callback)` | Execute a block (i.e. trigger another action). | _†Identical_ |
| `Action.customAction(duration, stepHandler)` | Execute a custom stepping function over the action duration. | _†Identical_ |
|***Controlling the Node's Action Speed***|||
|***Manipulating the Action Speed of a Node***|||
| `Action.speedBy(delta, duration)` | Change how fast a node executes its actions by a relative value. | Yes |
| `Action.speedTo(speed, duration)` | Set how fast a node executes actions to a specified value. | _*No_ |

Expand Down Expand Up @@ -249,18 +270,18 @@ mySprite.run(MyActions.squashAndStretch(1.25));
mySprite.run(MyActions.squashAndStretch(2.0));
```

## Using Actions with display objects
## Running Actions on DisplayObjects

*Running actions in your canvas.*

```ts
// Hide me instantly.
// Hide me instantly!
mySprite.run(Action.hide(), () => {
console.log('where did I go?');
});
```

Display objects are extended with a few new methods and properties.
Display objects are extended with a few new methods and properties to make it easy to interact with actions.

| Property | Description |
| :----- | :------ |
Expand All @@ -273,10 +294,10 @@ Display objects are extended with a few new methods and properties.
| `run(action, completion)` | Run an action with a completion handler. |
| `runWithKey(action, withKey)` | Run an action, and store it so it can be retrieved later. |
| `runAsPromise(action): Promise<void>` | Run an action as a promise. |
| `action(forKey): Action \| undefined` | Return an action associated with a specific key. |
| `action(forKey): Action \| undefined` | Return an action associated with a specified key. |
| `hasActions(): boolean` | Return a boolean indicating whether the node is executing actions. |
| `removeAllActions(): void` | End and removes all actions from the node. |
| `removeAction(forKey): void` | Remove an action associated with a specific key. |
| `removeAction(forKey): void` | Remove an action associated with a specified key. |

### Running actions

Expand Down
61 changes: 22 additions & 39 deletions dist/Action.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,16 @@ import { TimingModeFn } from './TimingMode';
type TimeInterval = number;
/** Targeted display node. */
type TargetNode = PIXI.DisplayObject;
/** Any two dimensional vector. */
/** A vector (e.g. PIXI.Point, or any node). */
interface VectorLike {
x: number;
y: number;
}
/** Any object with a width and height. */
interface SizeLike {
width: number;
height: number;
}
/** Any object containing an array of points. */
interface PathLike {
points: VectorLike[];
Expand Down Expand Up @@ -125,13 +130,8 @@ export declare abstract class Action {
*
* This action is reversible.
*/
static moveBy(x: number, y: number, duration: TimeInterval): Action;
/**
* Creates an action that moves a node relative to its current position.
*
* This action is reversible.
*/
static moveByVector(vec: VectorLike, duration: TimeInterval): Action;
static moveBy(delta: VectorLike, duration: TimeInterval): Action;
static moveBy(dx: number, dy: number, duration: TimeInterval): Action;
/**
* Creates an action that moves a node horizontally relative to its current position.
*
Expand All @@ -150,14 +150,8 @@ export declare abstract class Action {
* This action is not reversible; the reverse of this action has the same duration but does not
* move the node.
*/
static moveTo(position: VectorLike, duration: TimeInterval): Action;
static moveTo(x: number, y: number, duration: TimeInterval): Action;
/**
* Creates an action that moves a node to a new position.
*
* This action is not reversible; the reverse of this action has the same duration but does not
* move the node.
*/
static moveToPoint(point: VectorLike, duration: TimeInterval): Action;
/**
* Creates an action that moves a node horizontally.
*
Expand All @@ -180,11 +174,11 @@ export declare abstract class Action {
*
* @param path A path to follow, or an object containing an array of points called `points`.
* @param duration The duration of the animation.
* @param asOffset When true, the path is relative to the node's current position.
* @param orientToPath When true, the node’s rotation turns to follow the path.
* @param fixedSpeed When true, the node's speed is consistent across different length segments.
* @param asOffset (Default: true) When true, the path is relative to the node's current position.
* @param orientToPath (Default: true) When true, the node’s rotation turns to follow the path.
* @param fixedSpeed (Default: true) When true, the node's speed is consistent for each segment.
*/
static follow(path: VectorLike[] | PathLike, duration: number, asOffset?: boolean, orientToPath?: boolean, fixedSpeed?: boolean): Action;
static follow(path: PathLike | VectorLike[], duration: number, asOffset?: boolean, orientToPath?: boolean, fixedSpeed?: boolean): Action;
/**
* Creates an action that moves the node along a path at a specified speed, optionally orienting
* the node to the path.
Expand All @@ -193,11 +187,11 @@ export declare abstract class Action {
* with the same speed.
*
* @param path A path to follow.
* @param speed The velocity at which the node should move in world units per second.
* @param asOffset When true, the path is relative to the node's current position.
* @param orientToPath If true, the node’s rotation turns to follow the path.
* @param speed The velocity at which the node should move, in world units per second.
* @param asOffset (Default: true) When true, the path is relative to the node's current position.
* @param orientToPath (Default: true) When true, the node’s rotation turns to follow the path.
*/
static followAtSpeed(path: VectorLike[] | PathLike, speed: number, asOffset?: boolean, orientToPath?: boolean): Action;
static followAtSpeed(path: PathLike | VectorLike[], speed: number, asOffset?: boolean, orientToPath?: boolean): Action;
/**
* Creates an action that rotates the node by a relative value (in radians).
*
Expand Down Expand Up @@ -242,14 +236,9 @@ export declare abstract class Action {
*
* This action is reversible.
*/
static scaleBy(value: number, duration: TimeInterval): Action;
static scaleBy(x: number, y: number, duration: TimeInterval): Action;
/**
* Creates an action that changes the x and y scale values of a node by a relative value.
*
* This action is reversible.
*/
static scaleByVector(vector: VectorLike, duration: TimeInterval): Action;
static scaleBy(scale: number, duration: TimeInterval): Action;
static scaleBy(size: VectorLike, duration: TimeInterval): Action;
static scaleBy(dx: number, dy: number, duration: TimeInterval): Action;
/**
* Creates an action that changes the x scale of a node by a relative value.
*
Expand All @@ -268,15 +257,9 @@ export declare abstract class Action {
* This action is not reversible; the reverse of this action has the same duration but does not
* change anything.
*/
static scaleTo(value: number, duration: TimeInterval): Action;
static scaleTo(scale: number, duration: TimeInterval): Action;
static scaleTo(size: SizeLike, duration: TimeInterval): Action;
static scaleTo(x: number, y: number, duration: TimeInterval): Action;
/**
* Creates an action that changes the x and y scale values of a node.
*
* This action is not reversible; the reverse of this action has the same duration but does not
* change anything.
*/
static scaleToSize(size: VectorLike, duration: TimeInterval): Action;
/**
* Creates an action that changes the y scale values of a node.
*
Expand Down
Loading
Loading