Views

Views

Overview

View files are contained in the views directory. View files contain data about a scene. The view maintains a list of actors within the scene with details about how they configured. Whether the actors are used within the scene is dependent if the scene draws the actor.

• Parameters, for an actor, can be defined in both the scene and the view
• Parameters defined for an the actor, within the scene, will override the parameters defined for an actor in the view.

Metro supports view files of the following format:

• YAML (.yaml or .yml)
• JSON (.json)

A scene will attempt to load view files in the following order:

• YAML
• JSON

You may also register a new view file format if none of these meet your needs.

A Scene's View

Default Scene Name

By default every scene will automatically look for a view file. The name of the view file is based on the name of the scene.

The name of the following scene is tutorial:

class TutorialScene < GameScene ; end

The view file associated with this scene would be found:

• views/tutorial.yaml or views/tutorial.yml
• views/tutorial.json

Scene's with Custom Names

If the name of the scene is changed from the default, the view name will also change to match the custom scene name.

The name of the following scene is explicitly set to final:

class HardestLevelScene < GameScene
  scene_name :final
end

The view file associated with this scene would be found at:

• views/final.yaml or views/final.yml
• views/final.json

Custom View Name

A scene may also explicitly define a view name. This is useful if the default name is not useful or appropriate. You may also want to share a view file across many scenes.

The name of the scene uses the default scene name. The view name is explicitly set to first_level:

class EasiestLevelScene < GameScene
  view_name :first_level
end

The view file associated with this scene would be found at:

• views/first_level.yaml or views/first_level.yml
• views/first_level.json

YAML Views

YAML for Ruby is a common configuration found across numerous applications.

The layout of a YAML view file will define all of the names of the actors as the top-level keys. Each actor then defines a hash of details. All keys used may be either strings or symbols.

class TitleScene < GameScene
  draws :galaxy
end

A view file would contain details about the galaxy actor.

galaxy:
  model: metro::ui::image
  image: galaxy.jpeg
  position: "75,410,0"
  color: rgba(255,255,255,0.4)
star:
  model: metro::ui::image
  image: star.jpeg
  position: "255,80,0"
  color: rgba(255,255,255,1.0)

NOTE: A star actor is defined in the view. The scene will not draw this actor because the star has not been specified in the list of actors that will be drawn.

NOTE: Position defines three numeric points separated by commas that is surrounded by quotes. This is done on purpose. Without the quotes the Ruby YAML parser may assume that the position is one giant number.

YAML Alias and Anchors

A very powerful feature of YAML is the ability to define a hash of properties and assign an anchor to it. This anchor allows you to reference it within other places within the same YAML document.

The use of anchors and aliases can help curb redundancy. In this example we define an actor named story_instruction and assign it the anchor &instruction. We then create two instructions which alias *instruction.

story_instruction: &instruction
  model: metro::ui::label
  color: "rgba(255,255,255,0.0)"
  align: "center"
story_01:
  <<: *instruction
  location: "320,200,1"
  text: "To get around use the W, A, S, D keys"
story_02:
  <<: *instruction
  location: "320,240,1"
  text: "To swing your sword use the space bar or left mouse button"

The scene would then draw the two story instructions.

class TutorialScene < GameScene
  draws :story_01, :story_02
end

JSON

The [JSON](JSONLint is a JSON Validator format is supported.

Registering a new view format

Metro provides an interface to define support for new view formats.

Registering a Parser

A parser is any class that adheres to the following format:

class CustomViewFormatParser
  #
  # Given the name of the view determine if a view file exists with your given
  # format.
  #
  # @param [String] view_path the path of the view to find (without the file
  #   extension which should be added by the parser)
  # @return a true if the view exists in this format.
  #
  def self.exists?(view_path)
    File.exists? "#{view_path}.#{format}"
  end

  #
  # Return a hash of the view content.
  #
  def self.parse(view_path)
    content = File.read "#{view_path}.#{format}"
    # ... this is where you would parse the string content into a hash ...
    content_as_hash
  end

  #
  # Return a symbol name of the format
  #
  def self.format
    :custom
  end
end

The parser is then registered with Metro::Views::Parsers.

Metro::Views::Parsers.register CustomViewFormatParser

Registering a Writer

View formats also need to support the ability to write. This provides the ability for changes to be persisted when necessary in the edit mode.

A writer is any class that adheres to the following format:

class CustomViewFormatWriter

  #
  # @param [String] view_path the path of the view to write (without the file
  #   extension which should be added by the writer)
  # @param [Hash] content a hash representation of the content to be saved
  #
  def self.write(view_path,content)
    # Open the file, connection, database, etc.
    # Convert the content to format
    # Save converted content to location
  end

  #
  # Return a symbol name of the format
  #
  def self.format
    :custom
  end
end

The parser is then registered with Metro::Views::Writers.

Metro::Views::Writers.register CustomViewFormatWriter

A Parser can also be a Writer

The YAML format and JSON format define the parser and the writer interface within the same file. This is a valid implementation.

class CustomViewFormat

  def self.format
    :custom
  end

  def self.exists?(view_path)
    File.exists? "#{view_path}.#{format}"
  end

  #
  # Return a hash of the view content.
  #
  def self.parse(view_path)
    content = File.read "#{view_path}.#{format}"
    # ... this is where you would parse the string content into a hash ...
    content_as_hash
  end

  #
  # @param [String] view_path the path of the view to write (without the file
  #   extension which should be added by the writer)
  # @param [Hash] content a hash representation of the content to be saved
  #
  def self.write(view_path,content)
    # Open the file, connection, database, etc.
    # Convert the content to format
    # Save converted content to location
  end

end

Metro::Views::Parsers.register CustomViewFormat
Metro::Views::Writers.register CustomViewFormat