hrm-cpu
Version:
Run Human Resource Machine programs in JavaScript
214 lines (150 loc) • 5.52 kB
Markdown
# hrm-cpu
## Run Human Resource Machine programs in JavaScript
This is a JavaScript runtime for the programs you write in the game
[Human Resource Machine](http://tomorrowcorporation.com/humanresourcemachine)
> Human Resource Machine is a puzzle game. In each level, your boss gives you a job. Automate it by programming your little office worker! If you succeed, you'll be promoted up to the next level for another year of work in the vast office building. Congratulations!
### NPM
`npm install hrm-cpu`
### Usage
Requires node 4.x - uses ES6
#### Basic Usage
```javascript
const HrmCpu = require( 'hrm-cpu' )
//source is a string in the Human Resource Machine program format
const source = loadSomeSourceFile()
//the initial state of the inbox - treated as FIFO
const inbox = [ 5, 18 ]
//initial memory state - set just slot 9 to 0
const tiles = {
9: 0
}
const outbox = HrmCpu( source, inbox, tiles ).run()
console.log( outbox )
```
Some levels don't require any floor tiles, in which case you can do:
```javascript
const outbox = HrmCpu( source, inbox ).run()
```
Some levels don't require an inbox, but if this is the case they must have floor
tiles:
```javascript
const outbox = HrmCpu( source, [], tiles ).run()
```
#### Advanced Usage
Also see examples directory or try running the tests with mocha
##### Factory overloads
```javascript
HrmCpu( state )
HrmCpu( options )
HrmCpu( source, inbox )
HrmCpu( source, options )
HrmCpu( source, inbox, tiles )
HrmCpu( source, inbox, floor )
```
HrmCpu is a factory function that returns an object with some properties and
the functions `run` and `step`
```javascript
{
options: {...},
state: {...},
run: ( cb ) => ...,
step: ( cb ) => ...
}
```
Regardless of which overloads you choose, the factory requires a source file, and
either of, or both of, inbox and floor state
If `run` is called synchronously it runs the whole program and returns the outbox
If `step` is called synchronously it executes a single line of the program, and
returns the program state
If `run` is called asynchronously it runs the whole program and then calls the
callback with `( err, outbox, state )`
If `step` is called asynchronously it executes a single line and calls with
`( err, state )`
##### State
The state object when set to the initial defaults looks like:
```javascript
{
program: [],
accumulator: null,
inbox: [],
outbox: [],
memory: [],
counter: 0,
steps: 0,
running: false
}
```
##### Options
Passed in options extend the default options, which are:
```
{
source: '',
inbox: [],
tiles: [],
columns: Infinity,
rows: Infinity,
commands: [ 'INBOX', 'OUTBOX', 'COPYFROM', 'COPYTO', 'ADD', 'SUB', 'BUMPUP', 'BUMPDN', 'JUMP', 'JUMPZ', 'JUMPN' ],
dereferencing: true,
maxSteps: 5000,
maxSize: 255,
minValue: -999,
maxValue: 999
}
```
These match the constraints of the actual game
`source`, `inbox` and `tiles` are described above
`columns` and `rows` describe the floor layout - these determine the valid floor
addresses and if set and your program tries to access a tile outside of these,
an error will be thrown or sent to your callback, depending on whether you used
the sync or async call
`commands` are the commands allowed for the current program - for example, in
the early levels many commands are not yet available
`dereferencing` is whether or not the program can access memory indirectly eg `[12]`
`maxSteps` is the maximum number of steps your program can run
`maxSize` is the maximum length of a program, not counting labels and comments.
A jump only counts as one line
`minValue` is the minimum value that you can hold in your hand
`maxValue` is the maximum value that you can hold in your hand
##### Async example
```javascript
HrmCpu( source, inbox, tiles ).run( ( err, outbox ) => {
if( err ){
console.error( err )
} else {
console.log( outbox )
}
})
```
##### Get program state from run
```javascript
HrmCpu( source, inbox, tiles ).run( ( err, outbox, state ) => {
if( err ){
console.error( err )
} else {
console.log( state )
}
})
```
### Related projects
#### Runtimes
* [C++ assembler/runtime](https://github.com/LRFLEW/HRM-CCPU)
* [JavaScript runtime](https://github.com/sixlettervariables/hrmsandbox)
#### Parsers
* [Expression Grammar](https://github.com/sixlettervariables/hrm-grammar)
* [ES6 parser](https://github.com/nrkn/hrm-parser)
#### Comment/label decoders & encoders
* [JavaScript decoder](https://github.com/nrkn/hrm-image-decoder)
* [Java decoder](https://gist.github.com/sendow/4df27a857000deb18cf9)
* [Java encoder](https://gist.github.com/sendow/045f01668f976691ff6b)
#### Viewers
* [Program Viewer, web](https://github.com/AlanDeSmet/human-resource-machine-viewer)
#### Solutions
* [Solutions and speed/size hacks, exploits etc](https://github.com/atesgoral/hrm-solutions)
#### Utils/data
* [Level data](https://github.com/atesgoral/hrm-level-data)
* [Inbox Generator](https://github.com/atesgoral/hrm-level-inbox-generator)
* [Outbox Generator](https://github.com/atesgoral/hrm-level-outbox-generator)
Please let me know if you know of any others!
### License
MIT