Fixups for older guides (#36)

* Updated older guides for newer GameStartr

* Slight endline, heading fixes in Things.md
This commit is contained in:
Josh Goldberg
2017-01-27 01:19:31 -08:00
committed by GitHub
parent 89fce6c0f1
commit 9f968d9673
8 changed files with 195 additions and 238 deletions
+52
View File
@@ -0,0 +1,52 @@
# Events
This is a general guide about in-game events for all FullScreenShenanigans projects.
## TimeHandlr
TimeHandlr is a module used for setting timed events.
It's a more flexible alternative to JavaScript's `setTimeout` and `setInterval`.
It schedules events in time slots that are handled at each game upkeep, which is fired every 16 ms.
You can use it to add your own events using `addEvent`.
The first two arguments to `addEvent` specify what function to call and after how many upkeeps, respectively.
```javascript
// Sets a Thing to shift right by 2 after 100 game upkeeps.
FSP.timeHandler.addEvent(
(): void => FSP.physics.shiftHoriz(thing, 2),
100);
```
Events can also be added to repeat, similar to using `setInterval`.
A new third argument, `numRepeats`, is what specifies how many times to repeat, and anything after that are the arguments to the callback function.
The event will repeat every however many upkeeps, that many times, until it's repeated the specified number of times or the callback function returns `true`.
`Infinity` is allowed to be passed for `numRepeats`, which will cause the event to continuously repeat until it returns `true`.
```javascript
// Sets a Things to shift right by 2 after 100 game upkeeps, repeating 5 times.
FSP.timeHandler.addEventInterval(
(): void => FSP.physics.shiftHoriz(thing, 2),
100,
5);
```
More can be read about TimeHandlr on its [Readme](https://github.com/FullScreenShenanigans/TimeHandlr/blob/master/README.md).
## Sprite Cycles
A sprite cycle is a timed change in a Thing's visual class handled by TimeHandlr.
This is represented by a cycling through of selected sprites, where each phase lasts a specified time interval.
Sprite cycles are often used to simulate movement.
For example, you can show a character walking by adding a cycle between the walking and standing sprites.
```javascript
// Adds a walking/standing cycle to a Thing, cycling every 100 game ticks.
// "Moving" is the name of the cycle, to be referenced in the thing's .cycles property.
FSP.timeHandler.addClassCycle(
thing,
["walking", "standing"],
"moving",
100);
```
-5
View File
@@ -1,10 +1,5 @@
This is the general getting started guide for all FullScreenShenanigans projects. The guide will show you how to download and run any FullScreenShenanigans game as well as teach you about how to use the console to interact with the game.
### Table of Contents
1. [Obtaining the Source Code](#obtaining-the-source-code)
2. [Build Process](#build-process)
3. [Using the Console](#using-the-console)
## Obtaining the Source Code
+10 -16
View File
@@ -1,11 +1,5 @@
This guide will describe how inputs from the user (keyboard, mouse, etc.) are routed through InputWritr and how the DeviceLayr Gamepad can be used on top of it.
### Table of Contents
1. [InputWritr](#inputwritr)
1. [Events and Triggers](#events-and-triggers)
2. [Running Events](#running-events)
2. [DeviceLayr](#devicelayr)
# InputWritr
## Events and Triggers
@@ -17,13 +11,13 @@ Triggers are what tie inputs with events and are specific actions on the inputs
Events can be added using `addEvent` which takes in a trigger name, key code, and the function to run when the event is triggered.
```typescript
```javascript
inputWriter.addEvent("onKeyDown", 37, () => console.log("left button pressed"););
```
...and are removed with `removeEvent` which takes in the trigger and key code.
Events can be removed with `removeEvent`, which takes in the trigger and key code.
```typescript
```javascript
inputWriter.removeEvent("onKeyDown", 37);
```
@@ -32,12 +26,12 @@ Events can be triggered by any number of inputs.
Aliases are additional inputs that allow for an event to be triggered from multiple user sources.
They can be added and removed using `addAliasValues` and `removeAliasValues` which both take in the input and an array of key character codes as arguments.
```typescript
```javascript
inputWriter.addAliasValues("left", [65, 74, 49]); // keys a, j, and 1 respectively
inputWriter.removeAliasValues("left", [65, 74, 49]);
```
```typescript
```javascript
const inputWriter = new InputWritr({
"aliases": {
"left": [65, 37], // a, left button
@@ -55,14 +49,14 @@ const inputWriter = new InputWritr({
To run events, use `callEvent` and `makePipe`.
`makePipe` takes in a trigger and code label to get the alias from the event and returns a function to run the triggered event.
```typescript
```javascript
const leftKeyPipe: () => void = inputWriter.makePipe("onKeyDown", "left");
leftKeyPipe();
```
`callEvent` takes in the event function/trigger and a key code, then directly runs the event.
```typescript
```javascript
inputWriter.callEvent("onKeyDown", "left");
```
@@ -76,7 +70,7 @@ DeviceLayr has its own input and trigger mappings in addition to the mappings fo
Connected devices are detected and registered with `checkNavigatorGamepads` which automatically adds them to the list of added gamepads once called and returns the number
of gamepads added.
```typescript
```javascript
const numAdded = deviceLayer.checkNavigatorGamepapds();
console.log(${numAdded}` gamepads were added.`);
```
@@ -89,13 +83,13 @@ Aliases for gamepad triggers are binary signals for whether an active change was
`activateAllGamepadTriggers` checks the status of all registered gamepads and calls the equivalent InputWritr event if any triggers have occurred.
```typescript
```javascript
deviceLayer.activateAllGamepadTriggers();
```
To clear the status of all joysticks and buttons, use `clearAllGamepadTriggers`.
```typescript
```javascript
deviceLayer.clearAllGamepadTriggers();
```
+25 -11
View File
@@ -1,31 +1,45 @@
This is a general guide about Maps for all FullScreenShenanigans projects. This guide will explain the concept of Maps, Areas, and Locations within a game and how they're connected.
This is a general guide about Maps for all FullScreenShenanigans projects.
This guide will explain the concept of Maps, Areas, and Locations within a game and how they're connected.
### Table of Contents
1. [MapsCreatr](#mapscreatr)
2. [AreaSpawnr](#areaspawnr)
# MapsCreatr
MapsCreatr is a module that handles the storage of Maps, Areas, and Locations.
MapsCreatr is a module that handles the storage of Maps, Areas, and Locations.
A Map is a collection of Areas. An Area is a 2D space with predefined `x` and `y` boundaries and Things. Locations are entry points within an Area, where an entry point is where the player may end up after transitioning to a new Area.
A Map is a collection of Areas.
An Area is a 2D space with predefined `x` and `y` boundaries and Things.
Locations are entry points within an Area, where an entry point is where the player may end up after transitioning to a new Area.
Generally in a FullScreenShenanigans project, each Map information is stored in its own .js file, outlining all Areas and Locations within that map. When the game is started, MapsCreatr loads all this data, goes through every Map's raw JSON data to create a new Map object using ObjectMakr, and finally stores it for later reference.
Generally in a FullScreenShenanigans project, each Map information is stored in its own .js file, outlining all Areas and Locations within that map.
When the game is started, MapsCreatr loads all this data, goes through every Map's raw JSON data to create a new Map object using ObjectMakr, and finally stores it for later reference.
More can be read about MapsCreatr on its [Readme](https://github.com/FullScreenShenanigans/MapsCreatr/blob/master/README.md).
# AreaSpawnr
AreaSpawnr is a module that works with MapsCreatr to spawn Things in a certain Area.
When a new Area is entered by the player, AreaSpawnr gets that Area's information from MapsCreatr. AreaSpawnr uses this to spawn the Area's predefined Things (or PreThings) that exist in the current viewable area, or bounding box. Each PreThing has its own entry in the Area's `creation` property. PreThing attributes are defined here, such as `x` and `y` positioning. AreaSpawnr uses this information to determine which PreThings belong in the current bounding box and ultimately place them.
When a new Area is entered by the player, AreaSpawnr gets that Area's information from MapsCreatr.
AreaSpawnr uses this to spawn the Area's predefined Things (or PreThings) that exist in the current viewable area, or bounding box.
Each PreThing has its own entry in the Area's `creation` property.
PreThing attributes are defined here, such as `x` and `y` positioning.
AreaSpawnr uses this information to determine which PreThings belong in the current bounding box and ultimately place them.
More can be read about AreaSpawnr on its [ReadMe](https://github.com/FullScreenShenanigans/AreaSpawnr/blob/master/README.md).
## Entrances and Transporters
A Location is a named set of coordinates in an Area that can optionally be linked with a Thing. That Thing is called and entrance and it's where a player may end up after being transported to a Location. The Location's properties are located in the Area's JSON data and contain its `x` and `y` positioning and whether it contains entrance Thing. Entrances are a core part built into MapsCreatr.
A Location is a named set of coordinates in an Area that can optionally be linked with a Thing.
That Thing is called and entrance and it's where a player may end up after being transported to a Location.
The Location's properties are located in the Area's JSON data and contain its `x` and `y` positioning and whether it contains entrance Thing.
Entrances are a core part built into MapsCreatr.
A transporter is a Thing that allows the player to change Areas. They are a concept added by GameStartr projects out of necessity for the way Areas are traveled between. It links to a Location, which describes where the player ends up. When the transporter is triggered, it calls `setLocation`, which brings the player to the specified Location's coordinates.
A transporter is a Thing that allows the player to change Areas.
They are a concept added by GameStartr projects out of necessity for the way Areas are traveled between.
It links to a Location, which describes where the player ends up.
When the transporter is triggered, it calls `setLocation`, which brings the player to the specified Location's coordinates.
For example, In FullScreenMario, a Pipe is commonly used as a transporter and/or entrance. The Pipe the player enters is the transporter and links to where he/she comes out of the Pipe, which is the Location. This Location can link to an entrance Pipe or just coordinates. One-way Pipes will deposit the player in a new Location but the entrance Pipe won't allow entry.
For example, In FullScreenPokemon, a Door is commonly used as a transporter and/or entrance.
The Door the player enters is the transporter and links to where they come out of the Door, which is the Location.
This Location can link to an entrance Pipe or just coordinates.
+8 -13
View File
@@ -1,10 +1,5 @@
This guide will describe how mods and their triggers attach to FullScreenShenanigans projects.
### Table of Contents
1. [ModAttachr](#modattachr)
1. [Adding Mods](#adding-mods)
2. [Event Hooks](#event-hooks)
# ModAttachr
ModAttachr is a module that allows for extensible triggered mod events.
@@ -17,17 +12,17 @@ When an event is fired in the game, ModAttachr calls the corresponding events of
A mod can be added with `addMod`.
```typescript
```javascript
modAttacher.addMod({
name: "Infinite Health",
events: {
"onModEnable": function (mod: ModAttachr.IModAttachrMod): void {
"onModEnable": () => {
// event code when the mod is enabled
},
"onModDisable": function (mod: ModAttachr.IModAttachrMod): void {
"onModDisable": () => {
// event code when the mod is disabled
},
"onBattleStart": function (mod: ModAttachr.IModAttachrMod, opponent: IOpponent): void {
"onBattleStart": () => {
// event code when a battle starts
}
},
@@ -40,7 +35,7 @@ modAttacher.addMod({
When a mod is enabled, its `onModEnable` event is called; when a mod is disabled, its `onModDisable` event is called.
A mod can be toggled with `toggleMod`.
```typescript
```javascript
// Enables, disables, and toggles the mod.
modAttacher.enableMod("Infinite Health");
modAttacher.disableMod("Infinite Health");
@@ -49,18 +44,18 @@ modAttacher.toggleMod("Infinite Health");
To fire events use the module's `fireEvent` function.
```typescript
```javascript
// Fires the onBattleStart event for all mods.
modAttacher.fireEvent("onBattleStart");
```
To fire an event for one mod, use `fireModEvent`.
```typescript
```javascript
modAttacher.fireModEvent("onBattleStart", "Infinite Health");
// Passing in additional arguments.
const opponent: IOpponent = new Opponent();
const opponent = new Opponent();
modAttacher.fireModEvent("onBattleStart", "Infinite Health", opponent);
```
+12 -20
View File
@@ -1,14 +1,5 @@
This guide will describe how GamesRunnr runs upkeep functions and how FSPAnalyzer is used to schedule them in GameStartr projects.
### Table of Contents
1. [GamesRunnr](#gamesrunnr)
1. [Upkeep](#games-and-upkeep)
2. [Interval and Speed](#interval-and-speed)
3. [Pause and Play](#pause-and-play)
2. [FPSAnalyzer](#fpsanalyzer)
1. [Measure](#measure)
2. [Getters](#getters)
# GamesRunnr
GamesRunnr is a module for running a series of callbacks grouped into one interval.
@@ -20,7 +11,7 @@ These callbacks separately are referred to as games.
`upkeep` is a function that runs each game once.
`upkeepTimed` is a utility function for `upkeep` that times and returns the amount of time it takes to run all the games.
```typescript
```javascript
const totalTime: number = gamesRunner.upkeepTimed();
console.log(`It took `${totalTime}` ms.`);
```
@@ -30,14 +21,14 @@ console.log(`It took `${totalTime}` ms.`);
Each call of `upkeep` has a set time delay, in milliseconds, before it can be called again, called an interval.
To set the interval use `setInterval`.
```typescript
```javascript
gamesRunner.setInterval(20);
```
`speed` is a variable which represents the playback speed of the intervals, for example a speed of 2 makes the intervals go by twice as fast.
To set the value, use `setSpeed`.
```typescript
```javascript
gamesRunner.setSpeed(2);
```
@@ -46,20 +37,20 @@ gamesRunner.setSpeed(2);
GamesRunnr can pause and continue `upkeep` execution.
`pause` stops the execution of `upkeep` and cancels the next call of upkeep.
```typescript
```javascript
gamesRunner.pause();
```
`play` continues execution of `upkeep` by calling it.
```typescript
```javascript
gamesRunner.play();
```
Both `pause` and `play` allow for trigger functions to run when they are called by defining `onPause` and `onPlay`.
```typescript
const gamesRunner: IGamesRunnr = new GamesRunnr({
```javascript
const gamesRunner = new GamesRunnr({
games: [() => console.log("example function")],
onPause: () => console.log("upkeep is paused"),
onPlay: () => console.log("upkeep is resumed")
@@ -70,12 +61,13 @@ gamesRunner.play();
To toggle between the two, use `togglePause`.
```typescript
```javascript
gamesRunner.togglePause();
```
More can be read on GamesRunnr on its [Readme](https://github.com/FullScreenShenanigans/GamesRunnr/blob/master/README.md).
# FPSAnalyzr
## Measure
@@ -84,13 +76,13 @@ FSPAnalyzr is a module for recording and analyzing framerate measurements.
`measure` and is run at the end of every `upkeep` call.
```typescript
```javascript
fpsAnalyzer.measure();
```
It updates the value for the current timestamp and if there was a previous timestamp recorded, it adds an FPS measurement to the list of recorded measurements with `addFPS`.
```typescript
```javascript
fpsAnalyzer.addFPS(40);
```
@@ -98,7 +90,7 @@ fpsAnalyzer.addFPS(40);
FPSAnalyzer has a number of getter functions that return statistics and information on the recorded measurements.
```typescript
```javascript
fpsAnalyzer.getNumRecorded();
fpsAnalyzer.getTicker();
fpsAnalyzer.getMeasurements();
+37 -49
View File
@@ -1,29 +1,16 @@
This guide will describe how FullScreenShenanigans projects keep track of game information.
### Table of Contents
1. [ItemsHoldr](#itemsholdr)
1. [Local Storage](#local-storage)
2. [Items](#items)
3. [Updating](#updating)
4. [Clearing and Defaults](#clearing-and-defaults)
5. [Elements](#elements)
2. [StateHoldr](#stateholdr)
1. [Prefix](#prefix)
2. [Collections](#collections)
3. [Changes](#changes)
# ItemsHoldr
ItemsHoldr is a versatile container to store and manipulate values in localStorage, and optionally keep an HTML container to show these values.
The ItemsHoldr module is a wrapper around localStorage.
It lets GameStartr instances store data locally with default values and value-based event handlers.
## Local Storage
ItemsHoldr keeps track of items and their values while the game is running.
It can also save this information to `localStorage`.
Other websites also use `localStorage`, so ItemsHoldr has a prefix property to differentiate ItemsHoldr's information.
Other websites also use `localStorage`, so ItemsHoldr has a prefix property to differentiate its information.
```typescript
const itemsHolder: IItemsHoldr = new ItemsHoldr({
```javascript
const itemsHolder = new ItemsHoldr({
prefix: "FullScreenShenanigans"
});
```
@@ -32,7 +19,7 @@ const itemsHolder: IItemsHoldr = new ItemsHoldr({
To add, update, and remove an item in the collection, use `addItem`, `setItem`, and `removeItem` respectively.
```typescript
```javascript
itemsHolder.addItem("color", { value: "red" });
itemsHolder.setItem("color", "purple");
itemsHolder.removeItem("color");
@@ -41,7 +28,7 @@ itemsHolder.removeItem("color");
`increase` and `decrease` add and subtract from the item's value.
`toggle` flips the boolean value of the item.
```typescript
```javascript
itemsHolder.increase("weight", 14);
itemsHolder.decrease("weight", 10);
itemsHolder.toggle("started");
@@ -49,15 +36,15 @@ itemsHolder.toggle("started");
`checkExistence` can be used to check if there is an item under the specified key and if not, add it to the collection.
```typescript
```javascript
itemsHolder.checkExistence("color");
```
By default if an item does not exist when `setItem`, `getItem`, `increase`, or `toggle` are called, the item is then added to the collection.
Define `allowNewItems` to explicitly enable or disable this feature.
```typescript
const itemsHolder: IItemsHoldr = new ItemsHoldr({
```javascript
const itemsHolder = new ItemsHoldr({
allowNewItems: false
});
```
@@ -65,7 +52,7 @@ const itemsHolder: IItemsHoldr = new ItemsHoldr({
To manually update a changed item's value in localStorage, use `saveItem`.
To save all the items' values to localStorage, use `saveAll`.
```typescript
```javascript
itemsHolder.saveItem("color");
itemsHolder.saveAll();
```
@@ -74,7 +61,7 @@ itemsHolder.saveAll();
Auto saving, which updates an item's value in localStorage when the value is changed, can be enabled when making the ItemsHolder container.
```typescript
```javascript
const itemsHolder = new ItemsHoldr({
autoSave: true
});
@@ -83,7 +70,7 @@ const itemsHolder = new ItemsHoldr({
By default, this is disabled.
To toggle autoSave, use `toggleAutoSave`.
```typescript
```javascript
itemsHolder.toggleAutoSave();
```
@@ -91,7 +78,7 @@ itemsHolder.toggleAutoSave();
Triggers are functions that get run when an item's value equals the specified value.
```typescript
```javascript
itemsHolder.addItem("color", {
value: "cyan",
triggers: {
@@ -105,7 +92,7 @@ Modularity restricts an item's value to a range from 0 to the specified max.
When the value is changed, the `onModular` function is run `x / modularity` times, where `x` is the number the value was set to.
Each time the function is run, value gets set to `value % modularity`.
```typescript
```javascript
itemsHolder.addItem("counter", { value: 0 });
itemsHolder.addItem("time", {
value: 0,
@@ -119,14 +106,14 @@ itemsHolder.setItem("time", 100);
To clear all items from the collection, use `clear`.
```typescript
```javascript
itemsHolder.clear();
```
To clear the collection, but keep some items which will always be in the collection, use `valueDefault`.
```typescript
const itemsHolder: IItemsHoldr = new ItemsHoldr({
```javascript
const itemsHolder = new ItemsHoldr({
values: {
color: {
valueDefault: "red"
@@ -142,8 +129,8 @@ ItemsHolder.clear(); // "color" is still in the collection with a reset value of
To signal if a container should be made to hold HTML elements, assign a value to `doMakeContainer`.
```typescript
const itemsHolder: IItemsHoldr = new ItemsHoldr({
```javascript
const itemsHolder = new ItemsHoldr({
doMakeContainer: true
});
```
@@ -151,8 +138,8 @@ const itemsHolder: IItemsHoldr = new ItemsHoldr({
Changes to element values will show on the page if the container is appended to an element on the page.
To signal if an item is an element, assign `hasElement` to true.
```typescript
const itemsHolder: IItemsHoldr = new ItemsHoldr({
```javascript
const itemsHolder = new ItemsHoldr({
doMakeContainer: true,
values: {
color: {
@@ -168,8 +155,8 @@ const itemsHolder: IItemsHoldr = new ItemsHoldr({
If you want certain values to be represented differently on the page, use `displayChanges`.
These changes are hardcoded values that replace specified values when element items are updated.
```typescript
const itemsHolder: IItemsHoldr = new ItemsHoldr({
```javascript
const itemsHolder = new ItemsHoldr({
displayChanges: {
Infinity: "INF";
}
@@ -184,7 +171,7 @@ itemsHolder.setItem("limit", "Infinity");
`hasDisplayChange` checks to see if a value has a recorded change and `getDisplayChange` returns the entry to replace the value with.
```typescript
```javascript
itemsHolder.hasDisplayChange("Infinity");
const newValue: string = ItemsHolder.getDisplayChange("Infinity");
```
@@ -193,13 +180,14 @@ const newValue: string = ItemsHolder.getDisplayChange("Infinity");
`hideContainer` hides the container from view and `displayContainer` makes the container visible.
```typescript
```javascript
itemsHolder.hideContainer();
itemsHolder.displayContainer();
```
More can be read about ItemsHoldr on its [Readme](https://github.com/FullScreenShenanigans/ItemsHoldr/blob/master/README.md).
# StateHoldr
StateHoldr is a module for tracking changes of items in ItemsHolder in objects called collections.
@@ -207,7 +195,7 @@ Changes are key-value pairs of attributes for items and values.
A collection describes how named items in a group have been changed. For each item in the group, the collection will store a key-value pair of attributes and new values.
For example, a garage collection that contains a "car" item with "color" and "name" changes could be described as:
```typescript
```javascript
const garage: { [i:string]: { [i: string]: string } } = {
car: {
color: "red"
@@ -222,8 +210,8 @@ Collections allow for various attributes for a single item to be grouped togethe
Like ItemsHoldr, StateHoldr has its own prefix property.
All collections in StateHoldr are stored in ItemsHoldr prepended with the StateHoldr prefix.
```typescript
const stateHolder: IStateHoldr = new StateHoldr({
```javascript
const stateHolder = new StateHoldr({
ItemsHolder: new ItemsHoldr(),
prefix: "StateHolder"
});
@@ -236,7 +224,7 @@ StateHoldr always has one collection as its current collection.
`setCollection` sets the current collection.
```typescript
```javascript
stateHolder.setCollection("newCollection", {
car: {
color: "red"
@@ -246,7 +234,7 @@ stateHolder.setCollection("newCollection", {
If the name passed in is the name of a collection that already exists, that collection's old values will be used.
```typescript
```javascript
stateHolder.setCollection("newCollection", {
car: {
color: "red"
@@ -260,7 +248,7 @@ stateHolder.setCollection("newCollection"); // car is still in this collection
Collections aren't put into ItemsHolder until they are saved.
`saveCollection` saves the current collection to ItemsHolder.
```typescript
```javascript
stateHolder.saveCollection();
```
@@ -269,26 +257,26 @@ stateHolder.saveCollection();
To add a change to the current collection, use `addChange`.
`addChange` takes in the key of the item, an attribute of the item, and the value being stored.
```typescript
```javascript
stateHolder.addChange("car", "color", "red");
```
A change to a specific collection can be added with `addCollectionChange`.
```typescript
```javascript
stateHolder.addCollectionChange("otherCollection", "car", "color", "red");
```
To copy changes from an item in the current collection into a target object, use `applyChanges`.
```typescript
```javascript
const recipient: { [i: string]: string } = {};
stateHolder.applyChanges("car", recipient);
```
`getChanges` returns the changes for a specific item.
```typescript
```javascript
const changes: { [i: string]: string } = StateHolder.getChanges("car");
```
+51 -124
View File
@@ -1,49 +1,41 @@
This is a general guide about Things for all FullScreenShenanigans projects.
It will show you how in-game Things are stored and manipulated.
Everything you see in the game (trees, blocks, the player, etc.) is a Thing.
# Things
The Thing class is subclassed by a new class for everything (Tree class, Block class, Player class, etc.).
These Things can be manipulated to change their location and properties.
All the following code samples are written specific to `FSP` (FullScreenPokemon) but will work for other GameStartr projects.
This is a general guide about in-game Things for all FullScreenShenanigans projects.
### Table of Contents
1. [GroupHoldr](#groupholdr)
1. [Getting Groups](#getting-groups)
2. [Manipulating Things](#manipulating-things)
1. [Shifting Things](#shifting-things)
2. [Opacity](#opacity)
3. [Adding Things](#adding-things)
4. [TimeHandlr](#timehandlr)
5. [Thing Classes](#thing-classes)
6. [Sprites](#sprites)
1. [Sprite Cycles and Movement](#sprite-cycles-and-movement)
## Things
# GroupHoldr
Every in-game object in GameStartr games is a Thing.
Things and their classes are generated using [ObjectMakr](https://github.com/FullScreenShenanigans/ObjectMakr), which generates classes based on the inheritance structure given to it by its module settings.
GroupHoldr is a module that's used to store similarly typed information, such as Things. A module is a member of the game's instance that controls certain aspects of that instance. Each Thing has a `groupType` string property that determines what group it's considered to be in. For example, the groups in `FSP` are:
```javascript
const thing = FSP.objectMaker.make("MyThing");
```
* Text
* Character
* Solid
* Scenery
* Terrain
Most of the basic properties, like `height`, `width`, and `opacity` are defined in the parent Thing class.
ObjectMakr's `make` is a shortcut to initializing a new instance of a Thing class and assigning properties to it in one step.
GroupHoldr contains an Array for each of the groups; each Array contains all the Things of that type currently in the game. Things are added to their respective group when added to the game and removed when they die. For example, in `FSP`, solid objects like floors and blocks would be stored in the Solid group.
More can be read on ObjectMakr on its [Readme](https://github.com/FullScreenShenanigans/ObjectMakr/blob/master/README.md).
### Getting Groups
The groups are accessible both by static name and via passing in a String.
## Groups
Each Thing has a `.groupType` string defining which "group" of Things it belongs to.
These groups are stored within the GroupHoldr module, which contains an array or object for each group.
Things are added to their respective group when added to the game and removed when they die.
### Getting groups
The groups are accessible both by static name and via passing in a String.
```javascript
// Returns the Solid group
FSP.GroupHolder.getGroup("Solid");
FSP.groupHolder.getGroup("Solid");
// Returns the first Solid
FSP.GroupHolder.getGroup("Solid")[0];
FSP.groupHolder.getGroup("Solid")[0];
```
More can be read on GroupHoldr on its [Readme](https://github.com/FullScreenShenanigans/GroupHoldr/blob/master/README.md).
# Manipulating Things
## Physics
@@ -52,8 +44,6 @@ These define the bounding box for a Thing.
A Thing is essentially a rectangle, with its height, width, and location defined by these properties.
The coordinate system in which these Things are placed has an origin at the top left corner (0,0).
Things are also scaled from these raw measurements to actual in-game measurements using a predefined `unitsize`.
A `unitsize` of 1 means no scaling, while a `unitsize` of 2 means in-game measurements are doubled.
There are a number of ways to move Things, all of which are done by manipulating these 4 properties.
@@ -65,90 +55,96 @@ const otherThing = FSP.GroupHolder.getGroup("Solid")[1];
Physics methods are stored under the `physics` member of a GameStartr instance.
#### Shift
### Shift
You can use the shift functions `shiftVert` and `shiftHoriz`. These move the Thing up and down or left and right.
You can use the shift functions `shiftVert` and `shiftHoriz`.
These move the Thing up and down or left and right.
```javascript
// Shifts a Thing vertically by 1.
FSP.physics.shiftVert(thing, 1);
// Shifts a Thing horizontally by 1.
// Shifts a Thing horizontally by 1.
FSP.physics.shiftHoriz(thing, 1);
```
#### Set
### Set
The `set` functions (`setTop`, `setRight`, `setBottom`, or `setLeft`) moves the Thing to line up with the bounding property.
```javascript
// Sets the top bound of a Thing to 10.
// Sets the top bound of a Thing to 10.
FSP.physics.setTop(thing, 10);
// Sets the left bound of a Thing to 10.
// Sets the left bound of a Thing to 10.
FSP.physics.setLeft(thing, 10);
// Sets the bottom bound of a Thing to 10.
// Sets the bottom bound of a Thing to 10.
FSP.physics.setBottom(thing, 10);
// Sets the right bound of a Thing to 10.
// Sets the right bound of a Thing to 10.
FSP.physics.setRight(thing, 10);
```
#### Midpoints
### Midpoints
It's possible to set the Thing's midpoint using `setMidX`, `setMidY`, and `setMid` (the latter of which sets both the `x` and `y` midpoints). These functions make it so the Thing is centered on the given `x` and `y`.
It's possible to set the Thing's midpoint using `setMidX`, `setMidY`, and `setMid` (the latter of which sets both the `x` and `y` midpoints).
These functions make it so the Thing is centered on the given `x` and `y`.
```javascript
// Sets both x and y midpoints to 1 and 2, respectively.
// Sets both x and y midpoints to 1 and 2, respectively.
FSP.physics.setMid(thing, 1, 2);
// The above is equivalent to the following 2 function calls.
// The above is equivalent to the following 2 function calls.
FSP.physics.setMidX(thing, 1);
FSP.physics.setMidY(thing, 2);
```
Going along with setting midpoints, you can do that based on the midpoint of another Thing. Using `setMidXObj`, `setMidYObj`, and `setMidObj` you can shift a Thing so that its horizontal and/or vertical midpoint(s) are centered on that of another Thing.
Going along with setting midpoints, you can do that based on the midpoint of another Thing.
Using `setMidXObj`, `setMidYObj`, and `setMidObj` you can shift a Thing so that its horizontal and/or vertical midpoint(s) are centered on that of another Thing.
```javascript
// Aligns a Thing's horizontal and vertical midpoints with that of anotherThing.
// Aligns a Thing's horizontal and vertical midpoints with those of anotherThing.
// This is equivalent to the following 2 function calls combined.
FSP.physics.setMidObj(thing, otherThing);
// Aligns just the horizontal midpoint.
// Aligns just the horizontal midpoint.
FSP.physics.setMidXObj(thing, otherThing);
// Aligns just the vertical midpoint.
// Aligns just the vertical midpoint.
FSP.physics.setMidYObj(thing, otherThing);
```
#### Slide
### Slide
`slideToX` or `slideToY` will slide a Thing toward a target `x` or `y`, while limiting the total distance allowed (distance computed from the Thing's original midpoint).
```javascript
// Slides a Thing to x position 10, moving a max distance of 5.
// Slides a Thing to x position 10, moving a max distance of 5.
FSP.physics.slideToX(thing, 10, 5);
// Slides a Thing to y position 10, moving a max distance of 5.
// Slides a Thing to y position 10, moving a max distance of 5.
FSP.physics.slideToY(thing, 10, 5);
```
## Opacity
Opacity defines how transparent a Thing is. It's defined in the `opacity` property and ranges from 0 to 1 (0 = fully transparent, 1 = fully visible).
Opacity defines how transparent a Thing is.
It's defined in the `opacity` property and ranges from 0 to 1 (0 = fully transparent, 1 = fully visible).
You can set a Thing's opacity using `setOpacity`.
```javascript
// Sets a Thing's opacity to 1.
// Sets a Thing's opacity to 1.
FSP.physics.setOpacity(thing, 1);
// Sets a Thing's opacity to 0 (transparent).
// Sets a Thing's opacity to 0 (transparent).
FSP.physics.setOpacity(thing, 0);
```
# Adding Things
## Adding Things
You're able to add Things to the game via `addThing`, specifying the `x` and `y` positions (again this is relative to the top left corner of the screen).
The `x` is where the Thing's `left` bound will be and the `y` is where the Thing's `top` bound will be.
@@ -164,72 +160,3 @@ const second = FSP.things.add("FenceWide", first.right, first.top);
// Adds a Thing below another Thing.
FSP.things.add("FenceWide", second.left, second.bottom);
```
# TimeHandlr
TimeHandlr is a module used for setting timed events. It's a more flexible alternative to JavaScript's `setTimeout` and `setInterval`.
It schedules events in time slots that are handled at each game upkeep, which is fired every 16 ms.
You can use it to add your own events using `addEvent`. The first two arguments to `addEvent` specify what function to call and after how many upkeeps, respectively.
```javascript
// Sets a Thing to shift right by 2 after 100 game upkeeps.
FSP.TimeHandler.addEvent(
(): void => FSP.shiftHoriz(thing, 2),
100);
```
Events can also be added to repeat, similar to using `setInterval`.
A new third argument, `numRepeats`, is what specifies how many times to repeat, and anything after that are the arguments to the callback function.
The event will repeat every however many upkeeps, that many times, until it's repeated the specified number of times or the callback function returns `true`.
`Infinity` is allowed to be passed for `numRepeats`, which will cause the event to continuously repeat until it returns `true`.
```javascript
// Sets a Things to shift right by 2 after 100 game upkeeps, repeating 5 times.
FSP.addEventInterval(
(): void => FSP.shiftHoriz(thing, 2),
100,
5);
```
More can be read about TimeHandlr on its [Readme](https://github.com/FullScreenShenanigans/TimeHandlr/blob/master/README.md).
# Thing classes
Classes are generated using [ObjectMakr](https://github.com/FullScreenShenanigans/ObjectMakr), a module that dynamically generates the inheritance structure of classes.
It takes in the structure and a list of properties and the class objects are then constructed using this information.
When a FullScreenShenanigans game starts up, ObjectMakr receives the inheritance structure and properties list from an `objects.js` file.
It then generates prototypes for all of the internal classes (Box, Tree, etc.).
Most of the basic properties, like `height`, `width`, and `opacity` are defined in the parent Thing class.
ObjectMakr's `addThing` is a shortcut to initializing a new instance of a Thing class and assigning properties to it in one step.
More can be read about ObjectMakr on its [ReadMe](https://github.com/FullScreenShenanigans/ObjectMakr/blob/master/README.md).
# Sprites
Sprites comprise any visual you see in a FullScreenShenanigans game.
They are stored as string representations of an image, containing information about every pixel.
The game generates the image from this string in real-time.
More can be read about sprites in [PixelDrawer's](https://github.com/FullScreenShenanigans/PixelDrawr/blob/master/README.md) and [PixelRendr's](https://github.com/FullScreenShenanigans/PixelRendr/blob/master/README.md).
Each Thing class has a set of sprites relevant to it, usually different views (facing forward, to the left, etc.).
The game selects which sprite to use based on the Thing's full class name. For example, if the Player is facing left, its class could be "Player left".
## Sprite Cycles and Movement
A sprite cycle is a timed change in a Thing's class handled by TimeHandlr. This is represented by a cycling through of selected sprites, where each phase lasts a specified time interval.
Sprite cycles are often used to simulate movement. For example, you can show a character walking by adding a cycle between the walking and standing sprites.
```javascript
// Adds a walking/standing cycle to a Thing, cycling every 100 game ticks.
// "Moving" is the name of the cycle, to be referenced in the thing's .cycles property.
FSP.TimeHandler.addClassCycle(
thing,
["walking", "standing"],
"moving",
100);
```