A Toolkit To Create 8-bit Flavored Application
Ruby C Other
Latest commit 1be92c7 Sep 8, 2016 @remore committed on GitHub Add a note to FUEL-ROM.md
Permalink
Failed to load latest commit information.
bin
example
lib
test
.gitignore
CHANGELOG.md
FUEL-ROM.md
Gemfile
LICENSE
README.md
Rakefile
burn.gemspec

README.md

Burn - a handy toolkit to make 8-bit flavored applications from Ruby DSLs

Burn is a .nes rom file compiler in Ruby. For example, a .nes application below is written in less than 500 lines of Ruby DSL code, including graphic and sound resources.(code / online demo)

rubima wars pic

Burn works as a telnet application server too. Assuming you write this simple Ruby DSL:

declare do
  star <<-EOH

       11       
       11       
      1111      
      1111      
1111111111111111
 11111111111111
  111111111111  
   1111111111   
    11111111    
    11111111    
    11111111    
   1111  1111   
   11      11   
  1          1  

EOH
end

scene do
  main_loop <<-EOH
    star.x=20
    star.y-=3
    sprite "star"
EOH
end

With Burn, you can compile this to .nes:

star animated gif

and at the same time, you can run this as a telnet server application:

star animated telnet server app

Just like Recipes and Cookbooks are DSLs for the Chef rubygem, this dead simple DSL is for the Burn rubygem, and we call it Fuel.

Imagine an 8-bit application like ascii starwars movie can be created in seconds, seriously. Now is the time to go back and revisit what a low-resolution application is.

system menu example

Table Of Contents

Introduction

How It Works

Burn has two modes, :rom mode and :telnet mode.

For :rom mode, Burn uses cc65 executables embedded in its gemfile for compilation. The main workflow is as follows.

  • translate ruby DSL file into c source code
  • compile source to make executable(*.nes) by calling cc65
  • provide an emulator(JSNES) for rapid application development

Meanwhile, for :telnet mode Burn works like this:

  • translate ruby DSL file into CRuby source code
  • provide telnet server function to run the code on burn VM

Requirements

  • Ruby 1.9.1+
  • gcc (Windows users do not require this)

Burn supports all major OS like MacOS, Unix-like systems and Windows.

Getting Started

Installation

sudo gem install burn
sudo burn init

Quick Start

# :nes mode
echo "scene {label 'hello world'}" > main.rb
burn # make .nes rom and launch .nes emulator
ls tmp/burn/ | grep main.nes

# :telnet mode
echo -e "config(:app){ target :telnet }\nscene {label 'hello world'}" > main.rb
burn & # run telnet server
telnet localhost 60000

Examples are available at example/ folder. Please clone the repository using git clone https://github.com/remore/burn.git and play.

Handy Commands

# Use text file as FuelDSL to run telnet server
burn fuel README.md > main.rb && burn &
telnet localhost 60000

# More detailed usage of burn fuel command
burn fuel README.md -w 60 -h 20 -t 300

Fuel DSL

Currently example code is the best reference. For documentation, please see following materials:

Reference for :nes mode

Reference for :telnet mode(coming soon)

Additional reference material is TBD:

  • articles about #show, #sprite, #rand and #is_pressed are coming very soon

Notes

Why Burn

Primarily, to help the anti-piracy movement gain significant momentum. There are countless ways out there that emulate .nes games, but very few that create .nes rom file without hassle. This is the original reason why @remore has developed Burn.

Secondarily, to get back a lost love to video game programming. Having high-spec machine will not always make human beings happy. Sometimes we need a reminder to look back to an older era where many constrains still exist. You might think it's silly, but I'm serious. It's crazy fun to struggle.

Discussions and Conference Talks

A quick discussion at Reddit.com and HackerNews

A Talk at RubyKaigi 2014

Introduction at rubima(Rubyist Magazine)

Helpful Folks

  • Shiru - This project had never been born if I had not found this article
  • My friend from high school - I appreciate him for sending me fine-grained reviews as always
  • @josbrahol and @buzzedword sent me a great pull request which contains many grammatical errors
  • @kdb424 sent me a pull request to fix a typo

License

GPLv3

ToDos

Here are a few todo-memo for :nes mode.

  • New VM Support
    • compatability with enchant.js
  • Enhancement of Fuel DSL
    • for Screen, support screen scroll and simple sprite
    • for Screen, adding .bmp and .png support to make designing pattern table easier
    • for Sound, add triangle wave and noise effect
    • for Music, add custom instrument DSL
    • for Declare, support string and boolean declaration(currently only number and pattern table is supported)
  • Improvement of Internal Architecture
    • make cc65 alternative in Ruby
  • Other Feature To Be Supported
    • make Burn rubygem work with mruby(not soon)
  • Fix bugs
    • declaring 2x2 pattern works, however 2x1 pattern doesn't