The Crystal Programming Language Forum

Anyolite - Scripting with mruby in Crystal

Over the last year, I have developed a Crystal shard which allows for using mruby as a scripting language in Crystal projects. Essentially, the shard includes a full mruby interpreter into the app, and also provides macro methods to easily bind Crystal classes and methods to mruby.

Therefore, two powerful programming languages can be combined to compensate both of their most glaring weaknesses.

Anyolite is available here:, including examples, features, limitations and a documentation of all functions.

Anyolite was designed in a way that scripting support for applications has no major roadblocks and the developer doesn’t need to care about implementation details like coordinating garbage collecting or writing bindings for each single method. Anyolite does support:

  • Binding of entire module and class hierarchies with a single line of code
  • Keyword arguments and regular arguments
  • Structs, enums and unions
  • Generic types (as long as all possible types are specified)
  • Calling mruby procs from Crystal
  • Class inheritance

However, there are still some fundamental differences between Crystal and Ruby which need to be respected:

  • Crystal needs to know the type of mruby values at compiletime to convert them
  • Arrays and Hashes are only passed as copies (to avoid invalid types)
  • Pointers are passed as weak references
  • Symbols can not be passed to Crystal
  • Splat arguments are not supported
  • Only one function argument set can be bound to mruby, so overloading is not directly possible
  • Some annotations might be required to give Anyolite additional information

There are still some things I’d like to work on in the future, like:

  • Support for the MRI interpreter (this might take some time, though)
  • Converting scripts to bytecode at runtime and/or compiletime
  • Support for more argument types (like Time, Slice, …), if possible

Currently, Anyolite does explicitly NOT work on Windows and possibly ARM64 (not tested yet) due to a nasty ABI issue (see Issue #9533 ). Any help in dealing with this problem is appreciated.

Anyolite could be used, for example, in game engines (here full Windows support would definitely help), scientific applications or generally to improve the flexibility of Crystal software. As a matter of fact, Anyolite originated from my own plans for a 2D game engine with scripting support and also my experience with implementing scripting in applications.

I want myself and other developers to focus on the actual program instead of wasting hours and hours on the ungrateful task of binding functions to a scripting language - and that’s why I developed Anyolite.


This looks awesome and integrating mruby into a Crystal program of mine is something I’ve been wanting to do for a while, and I’m so happy to see a project like this out there. I cannot wait to try it out!


Release 0.13.0 is now out for Anyolite!

Release notes are available at

Most important points:

  • Regular Ruby is now supported as an alternative implementation to mruby
  • Instance/Class/Global Ruby variables can now be accessed via Anyolite
  • Scripts for mruby can be compiled to bytecode at Crystal compiletime

Documentation is still at 0.12.0, but I will fix this as soon as possible.