Unified Code Documentation Reference.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "31ca68d4",
   "metadata": {},
   "source": [
    "# Unified Code Documentation Reference\n",
    "\n",
    "## Table of Contents\n",
    " - [Section 1: Learning JavaScript](Section%201%2C%20Learning%20JavaScript.ipynb)\n",
    "    - [Basic Functions](#Basic-Functions)\n",
    " - [Section 6: The Canvas and Drawing Graphics](./Section%206%2C%20The%20Canvas%20and%20Drawing%20Graphics.ipynb)\n",
    "    - [Canvas API](#Canvas-API)\n",
    " - [Section 7: Beginnings of a Game](Section%207%2C%20Beginnings%20of%20a%20Game.ipynb)\n",
    "    - [GameObject API](#GameObject-API)\n",
    "    - [gameState Attributes](#gameState-Attributes)\n",
    "    - [gameState Functions](#gameState-Functions)\n",
    "    - [Game Engine Functions](#Game-Engine-Functions)\n",
    " - [Section 8, Drawing Game Objects, Changing Perspectives](Section%208%2C%20Drawing%20Game%20Objects%2C%20Changing%20Perspectives.ipynb)\n",
    "    - [Camera Object API](#Camera-Object-API)\n",
    " - [Section 9, Kinematics and Newtonian Mechanics](Section%209%2C%20Kinematics%20and%20Newtonian%20Mechanics.ipynb)\n",
    "    - [GameCollisionObject API](#GameCollisionObject-API)\n",
    " - [Section 10, Sprite Animations and Artwork](Section%2010%2C%20Sprite%20Animations%20and%20Artwork.ipynb)\n",
    "    - [Game Configuration Object](#Game-Configuration-Object)\n",
    "    - [Asset Builder API](#Asset-Builder-API)\n",
    "    - [Sprite Object API](#Sprite-Object-API)\n",
    "    - [Piskel App](#Piskel-App)\n",
    "    - [Sound Object API](#Sound-Object-API)\n",
    "    - [Sound Effects Generators](#Sound-Effects-Generators)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9f5edbd3",
   "metadata": {},
   "source": [
    "## Basic Functions\n",
    "\n",
    " - `element.println(val)`: Print data to area below code cell, and move to a new line.\n",
    " - `element.print(val)`: Print data to the area below the code cell, without moving to a new line.\n",
    " - `console.log(val)`: Print data to the web browser's developer console. Useful for debugging.\n",
    " - `alert(msg)`: Display an alert message.\n",
    " - `prompt(msg, default)`: Display a dialog prompt with the given message and default data in the text box. Returns the user submitted data in the text box.\n",
    " - `confirm(msg)`: Display a yes/no dialog to the user with the given message. Returns the user choice as a boolean (yes=true, no=false)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b208b542",
   "metadata": {},
   "source": [
    "## Canvas API\n",
    "\n",
    " - The Canvas:\n",
    "     - `canvas.width`: The width of the canvas drawing area in pixels.\n",
    "     - `canvas.height`: The height of the canvas drawing area in pixels.\n",
    " - The Painter (Context2D object):\n",
    "   - See [https://www.w3schools.com/graphics/canvas_reference.asp](https://www.w3schools.com/graphics/canvas_reference.asp) for documentation.\n",
    "   - Key Methods:\n",
    "       - `painter.drawImage`\n",
    "       - `painter.drawText`\n",
    "       - `painter.fillRect`\n",
    "       - `painter.strokeRect`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8302a4e",
   "metadata": {},
   "source": [
    "## GameObject API\n",
    "\n",
    "Functions:\n",
    "\n",
    " - `constructor(x, y, blockSize, sprites)`: To set extra properties when the object is created.\n",
    " - `update(timeStep, gameState)`: Update the location of the object.\n",
    " - `draw(canvas, painter, camera)`: Draw the object to screen.\n",
    " - `drawPreview(canvas, painter, box)`: Draw a preview of the object to a passed box. Used in the level editor.\n",
    " - `getHitBoxes()`: Get the list of hit boxes of an object (x, y, width, height). Only need to override if an entity that is not 1 block by 1 block in size. \n",
    " - `getBoundingBox()`: Get a box (x, y, width, height) which surrounds all of the hit boxes of this object. Does not need to be implemented.\n",
    "\n",
    "Variables/Attributes:\n",
    " - `this.x`: The x location of the object in game space, in blocks. (Not pixels).\n",
    " - `this.y`: The y location of the object in game space, in blocks. (Not pixels).\n",
    "\n",
    " \n",
    "## gameState Attributes\n",
    "\n",
    " - `lastTimeStamp`: Last time game was updated before this update, in milliseconds.\n",
    " - `paused`: Boolean flag to indicate if game has lost focus and is paused. Can be used to display a pause screen.\n",
    " - `canvas`: The canvas.\n",
    " - `painter`: The canvas painter or 2D rendering context.\n",
    " - `keysPressed`: An object which stores the key codes of all keys currently pressed down. Value of each key is set to true. Use the `in` operator to test for a key.\n",
    " - `cameras`: The cameras created for the game. Each camera converts game coordinates into screen coordinates, and can track an object.\n",
    " - `mouse.pressed`: If the mouse button is pressed down, a boolean.\n",
    " - `mouse.location`: The location of the mouse, an array with 2 floats (x, y).\n",
    " \n",
    "## gameState Functions\n",
    "\n",
    " - `addEntity(entity)`: Adds an entity to the game. `entity` should be a GameObject of entity type.\n",
    " - `addBlock(block)`: Adds a block to the game. `block` should be a GameObject of block type.\n",
    " - `getPlayers()`: Get the players in the game. Returns an array of `GameObject`s.\n",
    " - `getNeighboringBlocks(block)`: Get all of the blocks neighboring a given block. Accepts any `GameObject`, and returns a 3x3 array (x, then y indexed) of all blocks neighboring the provided object's x and y value. \n",
    " - `getBlocksAround(x, y)`: Same as `getNeighboringBlocks`, but accepts and x and y coordinate in game space instead of an object.\n",
    " - `getEntities()`: Get all of the entities currently loaded on screen. Returns an array of `GameObject`.\n",
    " - `getLevelBounds()`: Get the bounds of the entire game space measured in blocks. Returns a list with 4 values being `[x, y, width, height]`.\n",
    " - `enterZone(zoneName, cameraConfig = null)`: Enter a new zone, with the name `zoneName`, adding it to the zone stack. This current zone will resume once the entered zone exits without specifying a replacement. See the [Game Engine Functions](#Game-Engine-Functions) section for a full description of the `cameraConfig` parameter.\n",
    " - `exitZone(zoneName = null, cameraConfig = null)`: Exit this zone, terminating execution and removing it from the zone stack. An optional `zoneName` can be passed to specify a zone to replace this zone on the stack. If none is specified, the zone above this zone on the zone stack resumes execution, or if no zone is above it the game terminates. See the [Game Engine Functions](#Game-Engine-Functions) section for a full description of the `cameraConfig` parameter.\n",
    " \n",
    "## Game Engine Functions\n",
    "\n",
    " - `element.levelEditor(...)`: Open the game in the level editor.\n",
    " - `element.makeGame(...)`: Open the game in the game engine for playing.\n",
    " \n",
    "Both of the above methods accept the following arguments in-order:\n",
    " - `gameInfo`: The game configuration object for the game. See the [Game Configuration Object](#Game-Configuration-Object) section for more information on the game configuration object.\n",
    " - `entryZone` or `editZone`: A string, the zone to start the game in for `makeGame`, and the zone to edit for `levelEditor`.\n",
    "\n",
    "The `makeGame` function accepts one additional argument: \n",
    " - `cameraConfig`: A list or array of objects specifying the settings for the list of cameras to be used for viewing this zone. This setting is optional and not setting it causes the camera configuration to default to a single camera that tracks all players in the entered zone. The camera config objects can specify the following properties:\n",
    "    - `blockSize`: Size of a block in pixels, defaults to 32.\n",
    "    - `minBlocksShown`: A number, the minimum amount of blocks to display along the shortest axes. Defaults to 10.\n",
    "    - `maxBlocksShown`: A number, the maximum amount of blocks allowed to display along the longest axes. Defaults to 16. Set to `Infinity` to disable.\n",
    "    - `trackBox`: A list of 4 numbers all between 0 and 1, being `[x, y, width, height]`. Specifies the box to always keep the tracked players in relative to the camera's space on screen ((0, 0) being the top left corner of the camera and (1, 1) being the bottom right corner). Defaults to `[1/3, 1/3, 1/3, 1/3]`.\n",
    "    - `subCanvasBox`: A list of 4 numbers all between 0 and 1, being `[x, y, width, height]`. Specifies were in canvas space to display the camera's image. Defaults to `[0, 0, 1, 1]`, or the entire canvas area.\n",
    "    - `tracks`: A list of integers, the indices of players to track...\n",
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3da93813",
   "metadata": {},
   "source": [
    "## Camera Object API\n",
    "\n",
    " - `getBounds()`: Returns array with 4 elements (x, y, width, height), being the bounds of the camera in game space.\n",
    " - `transform([x, y])`: Accepts a length 2 array being x and y coordinates in pixel game space, returns them in screen space.\n",
    " - `transformBox([x, y, w, h])`: Same as transform, but accepts and returns a box.\n",
    " - `reverseTransform([x, y])`: Transforms a point from screen to game space."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e15644b4",
   "metadata": {},
   "source": [
    "## GameCollisionObject API\n",
    "\n",
    "Functions:\n",
    " - `handleCollisions(obj, side)`: Triggered whenever a collision occurs between this and another `GameCollisionObject`. Passes the other object, and the side of the current object that collided with the other object (`\"left\"`, `\"right\"`, `\"top\"`, `\"bottom\"`, or `\"inside\"` if the object is currently inside this one).\n",
    " \n",
    "Configurable Variables/Attributes:\n",
    " - `this._collisionSides`: An object literal that defaults to `{\"left\": true, \"top\": true, \"right\": true, \"bottom\": true}`. By setting it to an object with some of the above entries missing, those sides won't be checked for collisions. This allows for one-way platforms, gates, and other items. Can also be a list of objects, in which case each object corresponds to the hit box with the same index as returned by `getHitBoxes`.\n",
    " - `this._movable`: Defaults to false. Indicates an object can't be moved, like blocks. If set to true, the object will be moved when collisions occur with other solid objects.\n",
    " - `this._solid`: Defaults to true. If an object is not solid, collisions will still be detected, but objects that collide with it will move right through the object."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1067b6e",
   "metadata": {},
   "source": [
    "## Game Configuration Object\n",
    "\n",
    "The game configuration object should look like below anything that must be filled in is inside back-ticks (``` ` ` ```):\n",
    "\n",
    "```javascript\n",
    "let gameInfo = {\n",
    "    objects: { // All game object types needed for the game go here...\n",
    "        players: `An array, or list of player game object types. \n",
    "                  Players are entities that can be tracked by \n",
    "                  the camera and are never unloaded into chunks.`,\n",
    "        entities: `An array, or list of entity game object types.\n",
    "                   Entities can move, and aren't fixed to the grid`,\n",
    "        blocks: `An array, or list of block game object types.\n",
    "                 Blocks are fixed to the level grid, can take a maximum\n",
    "                 size of 1x1, and can't move.`\n",
    "    },\n",
    "    zones: { // All game zones go here...\n",
    "        `ZONE_NAME`: {\n",
    "            zoneData: `path to the level data on disk, a string. \n",
    "                       Level files are of json format. The level\n",
    "                       will be created in the level editor if it\n",
    "                       doesn't currently exist.`,\n",
    "            preUpdate: `Optional, a function that accepts the timeStep\n",
    "                        and gameState, and can return true to stop the\n",
    "                        game from update object this loop.`\n",
    "            postUpdate: `Optional, same as preUpdate, but return value\n",
    "                         does nothing.`\n",
    "            preDraw: `Optional, a function that accepts the canvas, painter,\n",
    "                      and gameState, and can return true to stop the game\n",
    "                      from drawing all objects this loop.`\n",
    "            postDraw: `Optional, same as preDraw, but return value\n",
    "                       does nothing.`\n",
    "            initGameState: `Optional, object specifying additional things\n",
    "                            to throw into the gameState before running`\n",
    "        },\n",
    "        `ANOTHER_ZONE_NAME_IF_WANTED`: {\n",
    "            ...\n",
    "        },\n",
    "    },\n",
    "    assets: {\n",
    "        sprites: {\n",
    "            `SPRITE_NAME`: {\n",
    "                image: `path to the image file on disk, a string`,\n",
    "                width: `Optional, the width of a tile. Defaults to the height of the image.`,\n",
    "                animations: {\n",
    "                    `ANIMATION1_NAME`: {\n",
    "                        frames: `Optional, a list of 0-based indexes/integers, the \n",
    "                                 frames to move through for this animation. Defaults \n",
    "                                 to moving through all frames sequentially.`\n",
    "                        speed: `Optional, the duration for a single frame to last on \n",
    "                                screen in milliseconds. Defaults to 16.`\n",
    "                        cycles: `Optional, number of times to repeat the animation. \n",
    "                                 Defaults to -1, or forever.`\n",
    "                        inset: `Optional, a list of 4 values [x, y, width, height] specifying\n",
    "                                the area of the sprite to draw to the passed area. Defaults\n",
    "                                to [0, 0, sprite.width, sprite.height].`\n",
    "                    },\n",
    "                    ...\n",
    "                }\n",
    "            }\n",
    "            `ANOTHER_SPRITE_NAME_IF_WANTED`: {\n",
    "                ...\n",
    "            },\n",
    "            ...\n",
    "        },\n",
    "        sounds: {\n",
    "            `SOUND_NAME`: {\n",
    "                source: `The path to the sound on disk, a string`,\n",
    "                background: `Optional, defaults to false, if true the sound is\n",
    "                             considered background music and will automatically\n",
    "                             loop and play when unmuted.`,\n",
    "                volume: `Optional, volume of sound between 0 and 1`\n",
    "            }\n",
    "            `ANOTHER_SOUND_NAME_IF_WANTED`: {\n",
    "                ...\n",
    "            }\n",
    "        }\n",
    "    }\n",
    "};\n",
    "```\n",
    "\n",
    "## Asset Builder API\n",
    "\n",
    "This is the \"`assets`\" object passed to the constructor of each `GameObject`.\n",
    "\n",
    " - `assets.sprites.SPRITENAME.buildSprite()`: Tells the sprite builder to return a sprite of the given `SPRITENAME` type. Names match those placed in the sprite data object. \n",
    " - `assets.sounds.SOUNDNAME.buildSound()`: Tells the sound builder to return a sound of the given `SOUNDNAME` type. Names match those placed in the sound data object. \n",
    " \n",
    "## Sprite Object API\n",
    "\n",
    "These are the objects returned by the sprite builder.\n",
    "\n",
    "Methods:\n",
    " - `setAnimation(name)`: Set the animation of the sprite via it's name. If already set to this animation does nothing.\n",
    " - `getAnimation()`: Get the current animation the sprite is in, or null if one hasn't been set.\n",
    " - `width` and `height`: Get the width/height of a single tile in the sprite.\n",
    " - `update(timeStep)`: Update the sprite by `timeStep` amount. Will move animation to correct frame.\n",
    " - `draw(painter, x, y, width, height)`: Draw the sprite with the passed painter to the provided box.\n",
    " - `setVerticalFlip(value)`: Set if the sprite should be vertically flipped when drawn. (true or false)\n",
    " - `setHorizontalFlip(value)`: Set if the sprite should be horizontally flipped when drawn. (true or false)\n",
    " - `isVerticallyFlipped()` and `isHorizontallyFlipped()`: Check if the sprite is vertically or horizontally flipped.\n",
    " \n",
    "## Piskel App\n",
    "\n",
    "Link to the Piskel App:\n",
    "\n",
    "[https://www.piskelapp.com/](https://www.piskelapp.com/)\n",
    "\n",
    "## Sound Object API\n",
    "\n",
    "These are the objects returned by the sound builder....\n",
    "\n",
    "Methods:\n",
    " - `setVolume(value)` and `getVolume()`: Get or set the volume of the sound, a number between 0 and 1.\n",
    " - `play()`: Play the sound.\n",
    " - `pause()`: Pause the sound.\n",
    " - `stop()`: Stop the sound (pause and reset time to 0).\n",
    " - `setTime(value)` and `getTime()`: Get and set the current time into the audio track.\n",
    "\n",
    "Static Methods:\n",
    " - `Sound.muteAll()`: Mute all sounds.\n",
    " - `Sound.unmuteAll()`: Unmute all sounds, resuming background music.\n",
    " - `Sound.muteAllBackground()`: Mute all background music only.\n",
    " \n",
    "## Sound Effects Generators\n",
    "\n",
    " - jsfxr: [https://sfxr.me/](https://sfxr.me/)\n",
    " - Leshy SFMaker: [https://www.leshylabs.com/apps/sfMaker/](https://www.leshylabs.com/apps/sfMaker/)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "40f0e7a7",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}