stormworks-screen-api
v0.1.4
Published
JS implementation of the Stormworks screen API
Downloads
5
Readme
stormworks-screen-api
Canvas-based JS/Typescript implementation of the Stormworks LUA screen API.
This library can be used to test and emulate controller designs outside of the game, as seen in Stormdev.
Getting started
Install the package:
With npm:
$ npm i --save stormworks-screen-api
With yarn:
$ yarn add stormworks-screen-api
Create an API instance
You can allow the API to create a canvas instance internally:
const stormworksScreenApi = screenApi();
// Retrieve the canvas element, e.g to include it in the DOM:
const canvasElement = stormworksScreenApi.getCanvasElement();
Or create your own canvas and provide it as an argument:
const myCanvasElement = document.getElementById('my-canvas');
if (!myCanvasElement) {
throw new Error('Failed to find canvas element');
}
const stormworksScreenApi = screenApi({
canvas: myCanvasElement,
});
The screen API methods are isolated under the screen
property, which makes it easy to pass to an emulator context:
const stormworksScreenApi = screenApi();
const screen = stormworksScreenApi.screen;
screen.setColor(255, 0, 0, 255);
screen.drawLine(0, 0, 10, 10);
screen.drawRectF(10, 10, screen.getWidth() / 2, screen.getHeight() / 2);
Compatibility
This library aims to be as accurate as possible compared to the in-game implementation, however, no guarantees are made. If a decision needs to be made between accuracy and practicality, practicality will always win.
drawMap
Note that currently drawMap
and map-related methods are not fully implemented - calls to these methods will succeed without rendering anything to the canvas.
Additional options:
The screenApi
method accepts a series of optional properties, which can be used to further configure how the API works, and how it renders elements onto the canvas.
All top-level properties are optional:
const stormworksScreenApi = screenApi({
// Provide a Canvas element; if not provided, one will be created internally
canvas: myCanvasElement,
// If a canvas element is not provided, these dimensions will be used to create a new canvas:
dimensions: {
width: 480,
height: 320,
},
// Override the values returned by `getWidth` and `getHeight`, can be used for emulation trickery:
reportDimensions: {
width: 64,
height: 64,
},
// Settings used while rendering onto the canvas. Default values are shown here:
drawSettings: {
lineWidth: 1.4,
fontSize: 5,
fontFamily: "'Screen Mono', 'Lucida Console', Monaco, monospace",
fontCharDimensions: {
width: 4,
height: 5,
},
defaultColor: [255, 255, 255, 255] as Color,
circle: {
lineSegmentIntervalsByRadius: [0, 20, 28],
lineSegmentIntervals: [8, 12, 16],
},
map: {
grass: [255, 255, 255, 255],
land: [255, 255, 255, 255],
ocean: [255, 255, 255, 255],
sand: [255, 255, 255, 255],
shallows: [255, 255, 255, 255],
snow: [255, 255, 255, 255],
},
},
});
Developing
A kitchen-sink is provided to visually inspect changes during development:
$ yarn dev
This will launch your primary browser on a page with a canvas element. You can use your developer console to test out the API locally, through the provided exported api at window.S
, e.g:
const screen = window.S.screen;
screen.drawText(1, 1, 'Hello!');
Stuff
Contributions are welcome! Please open tickets or - ideally - pull requests with your suggestions.