Skip to content
🎮 The Ruby 2D gem
Branch: master
Clone or download
Latest commit 43ce980 Apr 26, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets @ 7f3b5ec Bundle Linux dependencies Apr 18, 2019
bin Add ability to build macOS app bundles Jan 4, 2019
ext/ruby2d Match case of libFLAC.a in extconf.rb Apr 26, 2019
lib Bump version to 0.9.2 Apr 26, 2019
test Bundle dependencies with the gem Apr 7, 2019
.gitignore Add ability to take screenshot Jan 1, 2019
.gitmodules Merge all tests into `test/` directory Dec 25, 2016
.rspec Merge all tests into `test/` directory Dec 25, 2016
.travis.yml Bundle dependencies with the gem Apr 7, 2019
CODE_OF_CONDUCT.md Update markdown files Apr 20, 2019
Gemfile First! Oct 5, 2015
LICENSE.md
README.md Restore badge links in README Apr 20, 2019
Rakefile Bundle Linux dependencies Apr 18, 2019
appveyor.yml Bundle dependencies with the gem Apr 7, 2019
ruby2d.gemspec Remove current web backend Dec 12, 2018

README.md

Welcome to Ruby 2D!

Gem Build Status Gitter

This is the Ruby 2D gem. Check out the Ruby 2D website to learn how to get started building 2D apps in Ruby.

Development

To work on the gem locally, first clone this repo using:

git clone --recursive https://github.com/ruby2d/ruby2d.git

To keep the size of this repository small, Git submodules are used to reference test media and other assets. The --recursive flag ensures submodules are initialized and updated when this repo is cloned. If you happened to clone this repo without the --recursive flag, you can still initialize and update submodules with:

git submodule init
git submodule update --remote

Update these submodules at any time using git submodule update --remote or the rake update task.

Next, install dependencies:

  • With Bundler, run bundle install to get the required development gems.
  • Install the native graphics library Simple 2D by following the instructions in its README.
  • Install MRuby in order to build Ruby 2D apps natively. On macOS using Homebrew, run brew install mruby. On Ubuntu, use sudo apt install mruby libmruby-dev

Finally, run rake to build and install the gem locally.

Tests

Ruby 2D uses a combination of automated tests via RSpec and manual, interactive tests to verify the correctness of visual, audio, and input functionality. Build the gem and run all automated tests using the rake command. Build and run an interactive test in the test/ directory using rake test:<environment> <name_of_test>, for example:

# Run `test/testcard.rb` using the standard Ruby interpreter, MRI (CRuby)
rake test:int testcard

# Build `test/audio.rb` natively using MRuby and run
rake test:native audio

# Build `test/mouse.rb` for the web using WebAssembly and run in the default browser
rake test:web mouse

Contribute

Ruby 2D is an entirely open-source project (including its dependencies) built by dedicated folks who believe creating 2D applications should be simple, natural, and joyful, in the spirit of the Ruby language itself.

If you'd like to get involved, there are a number of ways to do so:

  • Suggest and implement new features. 🌟 Ruby 2D already does a lot, but there are plenty of new things it could do. If you have a feature request, or a suggestion on how to improve the domain-specific language, or something else to add, remove, or change, open a new issue and tell us about it. If you just want to casually talk through an idea without the pressure of opening an issue, send a note to the mailing list or chat with us on Gitter.

  • Add support for more platforms. 💻 Ruby 2D aims to be entirely cross platform. Help us test and improve the developer experience on existing platforms and add new ones.

  • Find and fix issues. 🐛 Your help identifying and fixing bugs, and improving performance along the way, will be critical to ensuring others have a solid experience using the library. Check out the issue tracker and have at it!

  • Write and review documentation. 📚 Vitally important to the success of every open-source project is documentation. We're off to a decent start, but there's always more to write and edit. Browse through the Ruby 2D website and help us identify areas to add clarity or fill in gaps. At the top of most pages, you'll see a link to "suggest an edit" which goes directly to the source file in the website repo.

  • Create and improve examples. 👾 We're currently a little light on sample applications to help folks get started. We'd love to get your ideas for small, single-file apps to guide users through specific features or techniques, which we collect in the examples repository. Check out the showcase to see what people are building and get some inspiration.

Technical contributions

In order to achieve such simplicity, a lot has to happen under the hood. Whether adding a feature or fixing a bug, try to do the following to ensure your pull request gets merged. Some of these might seem daunting, but we're happy to help along the way!

  • Check if there is an existing issue, and if not, open a new one to start a discussion. Before dedicating time and energy to an idea or fix, let's make sure it's consistent with the principles and goals of the project, and that we have a solid strategy in place to implement and test.

  • Use a subset of Ruby that works everywhere. Ruby 2D applications are, of course, written in Ruby. Some users may choose to harness the full power of the language, standard library, and ecosystem of gems by writing interpreted apps targeting the standard implementation, MRI. Others may want to target the web via WebAssembly, mobile devices, or build native desktop applications, all which make use of a different Ruby implementation called MRuby. Ruby 2D aims to support all of these use cases, even with the same app codebase. Your contribution must support a subset of Ruby that is compatible with and behaves similarly across MRI and MRuby. Beyond reading the documentation for each Ruby implementation, you can also try out code snippets on the command line using their respective REPLs: irb for MRI, and mirb for MRuby.

  • Comprehensively test your change. Unlike other Ruby libraries, not everything here can be easily covered with unit tests alone. We also need to make sure things look and sound right, inputs work as expected, and behavior is consistent across all platforms Ruby 2D supports.

Preparing a release

  1. Update the Simple 2D minimum version required in extconf.rb
  2. Run tests on all supported platforms
  3. Update the version number in version.rb, commit changes
  4. Create a new release in GitHub, with tag in the form v#.#.#, and write a little release note
  5. Run rake to build the gem, then push it to rubygems.org with gem push ruby2d-#.#.#.gem
  6. 🎉
You can’t perform that action at this time.