Gamefic SDK

A Ruby Interactive Fiction Framework

The Gamefic SDK provides development tools for writing games and interactive fiction with Gamefic.

Installation

Install the gem:

$ gem install gamefic-sdk

Usage

This section provides a fast and simple introduction to using the SDK. Go to the Gamefic website for in-depth guides and documentation.

Creating a New Project

Create a new project and go to its directory:

$ gamefic init my_game
$ cd my_game

Test the project by running the game on the command line:

$ rake ruby:run

The Ruby game works like a traditional text adventure:

Hello, world!
>

You can enter commands at the > prompt, but you haven't written any content, so there's not much to do yet. Enter QUIT to exit the game.

The Script Code

The plot for your narrative is defined in the plot.rb file. It should look something like this:

module Example
  class Plot < Gamefic::Plot
    UUID = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

    include Gamefic::Standard

    script do
      introduction do |actor|
        actor.tell "Hello, world!"
      end
    end
  end
end

UUID is a globally unique identifier. It can be useful if you want to add your game to online catalogs, such as the Interactive Fiction Database, but it's safe to delete if you don't need it.

'gamefic-standard' is a collection of baseline features that are frequently useful for interactive fiction. Inform developers should find it similar to Inform's Standard Rules. It defines common components like Rooms and Characters, along with in-game commands like GO, GET, and DROP to enable basic interactivity.

script is where you write the story itself. In the starter project, the only thing in the script is an introductory message.

Modifying the Script

Replace the contents of plot.rb with the following:

module Example
  class Plot < Gamefic::Plot
    UUID = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

    include Gamefic::Standard

    seed do
      @living_room = make Room, name: 'living room', description: 'This is your living room.'
      @bedroom = make Room, name: 'bedroom', description: 'This is your bedroom.'
      connect @living_room, @bedroom, 'north'
      @backpack = make Room, name: 'backpack', description: 'Your trusty backpack.', parent: @bedroom
      @book = make Room, name: 'book', description: 'Your favorite novel.', parent: @living_room
    end

    script do
      introduction do |actor|
        actor.parent = @living_room
        actor.tell "You're in your house."
      end
    end
  end
end

Enter rake ruby:run to test the game. Now that it has rooms and objects, you can perform in-game commands like LOOK AROUND, GO NORTH, and TAKE THE BACKPACK.

Making Games for the Web

The default game project includes tasks for building "web" apps using HTML, CSS, and JavaScript. Generate the code for a web build with the following command:

$ rake web:generate

Test the game in a browser by starting a server:

$ rake web:run

Open http://localhost:9000 to run the game in debug mode.

Build a standalone web game:

$ rake web:build

The game's HTML file and related assets will be generated in the web/build directory. The SDK uses opal](https://github.com/opal/opal) to compile Ruby code to JavaScript, so the web build does not require a Ruby interpreter. Open index.html in a browser to play the game.

Note: building the web app requires Node.js.

Example Projects

The gamefic-sdk repo includes several example projects that provide more complete demonstrations of Gamefic's features. To run an example, copy its plot.rb file to your own project.

Learning More

Go to the Gamefic website for more information about developing and building apps with Gamefic.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/castwide/gamefic-sdk.

License

The gem is available as open source under the terms of the MIT License.