#+TITLE:    React PICO-8
#+AUTHOR:	Jaxson Van Doorn
#+EMAIL:	jaxson.vandoorn@gmail.com
#+OPTIONS:  num:nil toc:nil

* React PICO-8

[[https://github.com/woofers/react-pico-8/actions][https://github.com/woofers/react-pico-8/workflows/build/badge.svg]] [[https://www.npmjs.com/package/react-pico-8][https://david-dm.org/woofers/react-pico-8.svg]] [[https://www.npmjs.com/package/react-pico-8][https://badge.fury.io/js/react-pico-8.svg]] [[https://www.npmjs.com/package/react-pico-8][https://img.shields.io/npm/dt/react-pico-8.svg]] [[https://github.com/woofers/react-pico-8/blob/main/License.txt][https://img.shields.io/npm/l/react-pico-8.svg]]

Run [[https://lexaloffle.com/pico-8.php][PICO-8]] game cartridges using a cusomtizable React component.

*[[https://jaxs.onl/react-pico-8/][Live Demo]]*

*Note:* This project is community made and not endorsed by Lexaloffle or the offical [[https://www.lexaloffle.com/pico-8.php][PICO-8]] Fantasy Console.

#+CAPTION: PICO-8 Player
#+ATTR_HTML: :style margin-left: auto; margin-right: auto;
[[./screenshots/boot.gif]]

* Installation

*Yarn*
#+BEGIN_SRC
yarn add react-pico-8
#+END_SRC

*npm*
#+BEGIN_SRC
npm install react-pico-8
#+END_SRC

* Usage

#+BEGIN_SRC js
import React from 'react'
import Pico8 from 'react-pico-8'
import { Controls,
         Reset,
         Pause,
         Sound,
         Carts,
         Fullscreen } from 'react-pico-8/buttons'
import 'react-pico-8/styles.css'

const App = () => (
  <Pico8 src="index.js"
         autoPlay={true}
         legacyButtons={false}
         hideCursor={false}
         center={true}
         blockKeys={false}
         usePointer={true}
         unpauseOnReset={true}
         placeholder="placeholder.png"
  >
    <Controls/>
    <Reset/>
    <Pause/>
    <Sound/>
    <Carts/>
    <Fullscreen/>
  </Pico8>
)
#+END_SRC

Simply add the game widget to the React application using JSX.

Be sure to include the ~.js~ ~src~ of the game cartridge generated from [[https://lexaloffle.com/pico-8.php][PICO-8]]'s web export.

If no buttons are nested in the component then the default [[https://lexaloffle.com/pico-8.php][PICO-8]] buttons will be used.

** Props
*** Src
Source of the game cartridge.  *Required*

This can be obtained from [[https://lexaloffle.com/pico-8.php][PICO-8]] by loading a game cart, then typing the command ~export index.html~.

[[https://lexaloffle.com/pico-8.php][PICO-8]] produces two files: the cartridge ~index.js~ and the player ~index.html~.

Since ~react-pico-8~ already has the game player embeded, only the ~.js~ file needs to be provided as the ~src~.
*** Auto Play
~autoPlay~ indicates if the game canvas should attempt to auto-play on page-load. *Default:* ~true~
*** Legacy Buttons
~legacyButtons~ is used to select the type of buttons. *Default:* ~false~
*** Hide Cursor
~hideCusor~ indicates if the cursor is hidden over the game canvas when the game is playing.  *Default:* ~false~
*** Center
~center~ indicates if the game is centred outside of fullscreen mode. *Default:* ~true~
*** Block Keys
If ~blockKeys~ is set keys which are used to interact with the game are blocked from scrolling when the game is running.

If un-set keys will only be blocked when the canvas is focused.  *Default:* ~false~
*** Use Pointer

If ~usePointer~ is set the pointer hand will be used on buttons.

If un-set a normal cursor will be used on all buttons which do not lead to a new page. *Default:* ~true~

*** Unpause On Reset

If ~unpauseOnReset~ is set hitting the reset button when paused will instantly reset the game.

If un-set the game will need to be resumed before it resets. *Default:* ~true~

*** Placeholder
The image to be used as a placeholder prior to starting the game.  If un-set, a black background will be used.  *Default:* ~''~