Burn

Burn is a free and open source framework that allows you to create 8-bit flavored application using Ruby DSL.

scene do
  label "Hello, World!"
end

Just like Recipe and Cookbook are DSL for Chef rubygem, this dead simple DSL is for Burn rubygem, and we call it Fuel. Burning this Fuel will produce this.

Here is another example. With Fuel DSL, you can even compose background music in 1 minute.

scene do
  label "Hello, World!"
  play "openning"
end

music "openning" do
  tempo :allegro
  channel "piano" do
    segno
    g :dotted
    g :eighth, :staccato
    a :dotted
    a :eighth, :staccato
    dal_segno
  end
end

Check the output from this.

Would you like to design retro 8-bit graphics? Here you go.

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

Please visit our project page for more example.

Table Of Contents

• Getting Started
  • How It Works
  • Installation
  • Quick Start
• Fuel DSL Methods
  • Scene
  • Sound
  • Music
  • Declare
• Burning Fuel DSL In Action
  • Programming With .rrb(Restricted Ruby) Syntax
• Notes
  • Personal Motivation
  • Helpful Folks
  • License
  • ToDos

Getting Started

How It Works

Internally, burn contains cc65 executables inside its gemfile and calls them to compile. Main workflow is as follows.

• translate ruby DSL file into c source code
• compile them to make executable(main.out) by calling cc65
• provide emulator(JSNES) for rpaid application development

This means what burn can do is always less than what cc65 can do.

Installation

gem install burn

Quick Start

echo "scene do{ label 'hello world'}" > main.rb
burn -p  # -p: open up emulator right after compilation

Fuel DSL Methods

Currently following DSL Methods are available. If you are newbie here, kindly visit project page first to see what you can do with Burn and Fuel DSL.

• Scene
• Sound
• Music
• Declare

Scene

label(string, x=0, y=1)

The label method can be used in a scene to display static string.

string String

Static string to display.

x Number

The horizontal coordinate to display, between 0 and 31.

y Number

The vertical coordinate to display, between 0 and 28.

scene do
  label "Hello, World!"
  label "Hello, World!", 4, 5
end

fade_in, fade_out

These methods can be used in a scene to fade in or out.

scene do
  label "Hello"
  fade_in
  main_loop
  fade_out
  goto "next"
end

play(song_title)

The play method can be used in a scene to play music.

song_title String

Song title to play.

scene do
  play "battle"
  stop
end

music "battle" do
  channel "string" do
    g   :dotted
    g   :eighth
    c   :half
  end
end

stop

The stop method can be used in a scene to stop music.

scene do
  stop "battle"
end

color(palette, color, lightness=:lighter)

The color method can be used in a scene to pick a color and set it to specific palette.

palette Symbol

Palette to set.

Palette Symbol	Description
:bg	Background color
:text	Foreground color
:palette_x1, :palette_x2, :palette_x3	Colors for :palette_x
:palette_y1, :palette_y2, :palette_y3	Colors for :palette_y
:palette_z1, :palette_z2, :palette_z3	Colors for :palette_z
:sprite	Sprite color

color Symbol

Color to set. Available color pattern is shown below.

Color Symbol
:white
:lightblue
:blue
:purple
:pink
:red
:deepred
:orange
:lightorange
:darkgreen
:green
:lightgreen
:bluegreen
:gray
:black

lightness Symbol

Lightness of the color to set. `:darkest`, `:darker`, `:lighter` and `:lightest` can be set.

scene do
  label "Hello, World!"
  color :text, :pink, :darker
end

wait(interval)

The wait method can be used in a scene to pause for certain period of time.

interval Fixnum

Period of time to pause.

scene do
  label "foobar"
  fade_out
  wait 100
  goto "somewhere"
end

goto(scene_name)

The goto method can be used in a scene to jump the scene specified.

scene_name String

Destination to jump.

scene "first" do
  label "good morning"
  goto "second"
end

scene "second" do
  label "hi there"
end

inline(code)

The inline method can be used in a scene to inject c source code manually to compile with cc65. Should be used for debugging purpose.

code String

C code to inject.

scene do
  inline "x=1+2;"
end

screen(map, vars)

The screen method can be used to inflate map data to a scene.

map String

Map data consists of hash keys of pattern design.

vars Hash

A list of pattern designs.

scene do
  screen <<-EOH, { A:"tile", B:"wave", C:"mountain"}

 AAAA  AA     AAA    AAA  AA  A 
 AA  A AA    AA AA  AA AA AA A  
 AA  A AA   AA   AA AA    AAA   
 AAAAA AA   AA   AA AA    AA    
 AA  A AA   AAAAAAA AA    AAA   
 AA  A AA   AA   AA AA AA AA A  
 AAAA  AAAA AA   AA  AAA  AA  A 

 BB   BB    BB   BBB   BBBBB    
 BB   BB    BB  BB BB  BB  BB   
  BB BB BB BB  BB   BB BB  BB   
  BB BB BB BB  BBBBBBB BBBB     
   BB    BB    BB   BB BB  BB   
   BB    BB    BB   BB BB  BB   
EOH
end

sound(effect_name)

The sound method in a scene can be used to play sound effect.

effect_name String

Name of sound effect to play.

scene do
  sound "dead"
end

sound "dead" do
  effect do
    velocity 15
    length 5
    pitch 200
  end
end

paint(dest, palette)

The paint method in a scene can be used to associate color palette with pattern designs inflated on the screen. Typically #paint is called along with #color and #screen method.

dest Range

Return value of #range(x_from, y_from, x_to, y_to) is expected. x_from and x_to takes the number between 0 and 255 while y_from and y_to takes the value between 0 and 239.

palette Symbol

Palette symbol to apply. Kindly refer candidate symbols listed at color section.

scene "title" do
  color :palette_x1, :deepred, :darker
  paint range("44px", "5px", "120px", "3px"), :palette_x # range takes String parameter

  color :palette_y2, :pink, :darkest
  paint range(30, 2, 30, 12), :palette_y # range method can take Number as well. In this case x_from and x_to takes the value between 0 and 31, while y_from and y_to takes the value from 0 and 29.
end

main_loop(rrb_source=nil)

The main_loop method in a scene can be used to repeat a block of code. More detail can be found at .rrb section.

rrb_source String

Source code written in .rrb(Resticted Ruby) syntax.

scene "title" do
  color :palette_x1, :deepred, :darker
  paint range("44px", "5px", "120px", "3px"), :palette_x # range takes String parameter

  color :palette_y2, :pink, :darkest
  paint range(30, 2, 30, 12), :palette_y # range method can take Number as well. In this case x_from and x_to takes the value between 0 and 31, while y_from and y_to takes the value from 0 and 29.
end

Sound

TBD

Music

TBD

Declare

TBD

Burning Fuel DSL In Action

Programming With .rrb(Restricted Ruby) Syntax

TBD(articles about #show, #sprite, #rand and #is_pressed are coming very soon)

Notes

Personal Motivation

Creating 8-bit flavored application mean neither outdated nor cheap, but good fit to rapid prototyping. It could be one of best options for education purpose as well.

Moreover, the executables built with burn will work at almost any OS. That said, consequently, burn is a multi-platform programming environment.

Helpful Folks

• Shiru - this project had never been born if I had not found this article

License

GPLv3

ToDos

• New VM Support
  • compatiblize 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