Skip to content

Tutorial

Jump to bottom Edit New page
Mo Morsi edited this page Feb 5, 2014 · 3 revisions

This page assumes you have access to an Omega server, if this is not the case see the Install document.

The command line & API mechanisms which to create an use a universe are covered here, see this for the Web UI Tutorial.

TOC

# Setup ## Login Credentials

On startup Omega sets up the various user accounts specified in the Config file. Certain users such as admin will be granted additional roles/privileges to serve particular duties. In admins case it is the complete set of privileges on all operations/entity in the simulation

Thus the user can used the admin username / pass configured in omega.yml to login and perform any functionality.

See the default Omega config file.

note On production systems, after additional users w/ restricted roles & privileges are created (see below), it is advisable to log out as the admin account and user a less-privileged role for interaction as a security precaution.

## URL

With a default omega-server launched like so:

ruby -Ilib ./bin/omega-server

The user has a few transport options through which to access the server with their client. The enabled transports are configured with the hostnames / IPs / ports which they listen on in the Config file.

For example if issuing a request using the Omega JSON-RPC API or the Omega Client DSL one would use the same server url:

   curl -X POST http://localhost:8888 -d \
     '{"jsonrpc":"2.0", "method":"stats::get",
         "params":["universe_id"], "id":"123"}'
  require 'rjr/nodes/web'
  require 'omega/client/dsl'
  dsl.rjr_node = RJR::Nodes::Web.new(:node_id =>    'client',
                                     :host    => 'localhost',
                                     :port    =>      '8888')
  login 'admin', 'nimda'
  invoke 'stats::get', 'universe_id'

  # Various examples below continue from this point
## Transport

Enabled/Disable particular transports in the Config file. For the remainder of this document we will be assuming the user is using TCP/IP.

Certain Omega JSON-RPC methods will check the transport which the request came in on and verify it supports a persistant connection, eg tcp, amqp, websockets, but not http. Those operations, including motel::track_location and manufactured::subscribe_to, will subscribe the client to periodic updates which are implemented via JSON-RPC notifications.

# Creating a Universe ## Creating The Cosmos

The Cosmos subsystem is responsible for cosmic entity level management such as tracking and providing access to galaxies, solar system, stars, planets, asteroids, moons, jump gates, and resources. See the Terminology page for the complete definitions & scope.

By default only privileged users, eg those w/ the superadmin role, eg admin, can create cosmos entities though all users, including the anon (anonymous) user can retrieve and view.

The Omega Omega Client DSL can be used to create a galaxy with a few systems and some children under those (continuing w/ the DSL example above)

galaxy 'Athena'    do |g|                             # galaxy name
  system  'Agathon',   'JJ7192',                      # system & star name, 
    :location => loc(-88,219,499) do |sys|            # system location
      planet 'Tychon', :movement_strategy =>          # planet name
       orbit(:speed => 0.012, :e => 0.33, :p => 1173, # planet loc ms (orbit)
             :direction => random_axis) do |pl|       # planet orbit axis
        moon 'Tyhon I',                               # moon name
          :location => rand_location(:min => 500,     # moon location
                                     :max => 2000)    #
                                                      # rinse and repeat...
        moon 'Tyhon II',
          :location => rand_location(:min => 500,
                                     :max => 2000)
    end

    planet 'Pegasus', :movement_strategy =>
      orbit(:speed => 0.031, :e => 0.42, :p => 1094,
            :direction => random_axis(:orthogonal_to => [0,1,0])) do |pl|
      moon 'Pegas',   :location => rand_location(:min => 500, :max => 2000)
    end

    # create 50 asteroids with resources
    0.upto(50){
      asteroid gen_uuid, :location =>
        rand_location(:min => 250, :max => 1000, :min_y => 0) do |ast|
        resource :resource => rand_resource, :quantity => 500
      end
    }
  end

  system 'Isocrates', 'IL9091', :location => loc(-104,-399,-438)
end
## Linking Systems Together

Any two systems may be linked together by creating a jump gate from one to another.

  # retrieve handles to two systems to link
  athena    = system('Athena')
  isocrates = system('Isocrates')
  
  # create jump gate from Athena to Isocrates at
  # specified location in Athena
  jump_gate athena, isocrates, :location => loc(1000, 1000, 1000)
  
  # create reverse jump gate in Isocates
  jump_gate isocrates, athena, :location => loc(-5555, -5000, 5050)

Note To allow entities to travel both ways make sure to create the reverse jump gate!

Note Omega also provides a utility which to graph systems by how they are linked together, see the bin/util/omega-cosmos-map.rb utility.

## Distributed Universes

Linking up disparate simulations so as to reference each other and allow ships / stations / other entities to move inbetween them is an advanced topic and will be covered elsewhere.

Users wishing to explore this should look at the distributed example in the project. (feel free to expand upon this and/or reach out to the community to throw around ideas).

## Creating Users

The Omega Omega Client DSL can be used to create users and roles and assign them like so:

  # creates new role w/ two privileges
  view_cosmos = Privilege.new(:id => 'view', :entity_id => 'cosmos')
  view_ship42 = Privilege.new(:id => 'view', :entity_id => 'manufactured_entity-ship42')
  custom_role = Role.new(:id => 'custom_role',
                         :privileges => [view_cosmos, view_ship42])
  role custom_role

  # create new user w/ id and pass and assign custom role to it
  user 'Osiris', 'secret' do
    role :custom_role
  end
## Creating User Entities

Creating user entities such as ships and stations is equally as simple with the Omega Omega Client DSL.

  starting_system = system('Athena')
  station('Osiris-station1') do |st|
    st.type         = :manufacturing
    st.user_id      = 'Osiris'
    st.solar_system = starting_system
    st.location     = loc(3000,3500,-2500)
  end

  ship('Osiris-ship1') do |st|
    st.type         = :mining
    st.user_id      = 'Osiris'
    st.solar_system = starting_system
    st.location     = loc(3100,3600,-2400)
  end
## Bringing It To Life

By default planets will orbit stars but not much else will be going on in your universe. All other entities will start off stopped, those that the user has access to will await furthur instruction

Note the admin may setup sequences of events and workflows to be invoked automatically periodically or at specific points during the simulation. See the Missions subsystem and Scripting Your Universe below.

To automate player controlled entities in realtime the user may use one of multiple mechanisms including

  • Writing a simple program issuing JSON-RPC requests to the server and tracking the entities via responses and callback notifications (feel free to use the Apache licensed RJR for this purpose)

  • Using the Omega Ruby API which provides many high level classes and mixins that can be used to manipulate the universe:

  Omega::Client::Corvette.owned_by('Osiris').each { |corvette|
    corvette.handle(:jumped) { |c|
      puts "#{c.id} jumped to #{c.system_id}"
    }
    corvette.handle(:attacked) { |c, event, attacker, defender|
      puts "#{c.id} attacked #{defender.id}"
    }

    # start_bot defines & uses some high level operations to
    # patrol the universe, seeking and attacking enemy ships.
    # feel free to override and/or define your own bot!
    corvette.start_bot
  }

There are multiple ways through which a human user can manipulate and interact with the universe in real time, see Interacting with your Universe below.

## Putting it all Together

You can find an example with all of the above here

TODO!

# Scripting Your Universe ## Setting Up Missions

The Missions DSL is a mechanism through which a privileged used can describe their intended sequence of events and when to invoke them.

Mission DSL operations & methods such as 'on mission assignment create_entity' or 'on mission resolution update_user_attributes' are used to describe custom simulation logic at a high level.

For example a simple timed mission involving generating an opponent and requiring the user to destroy it can be described like so:

  enemy_ship = 'BobBot-ship1'
  reward = Cosmos::Resource.new(:material_id => 'steel',
                                :quantity    => 50) 

  mission gen_uuid, :title => 'Search and Destroy',
    :creator_id => 'NPChad', :timeout => 360,
    :description => 'NPChad will reward you if you' \
                    'destroy BobBot\'s ship',
  
    :requirements => Requirements.shared_station,
  
    :assignment_callbacks =>
      [Assignment.create_entity(es,
        :type         =>     :corvette,
        :user_id      =>      'BobBot',
        :solar_system =>   rand_system,
        :location     => rand_location),
       Assignment.schedule_expiration_event,
       Assignment.subscribe_to(enemy_ship, "destroyed_by",
                               Event.create_victory_event)],
  
    :victory_conditions =>
      Query.check_entity_hp(enemy_ship),
  
    :victory_callbacks => 
      [Resolution.add_reward(reward),
       Resolution.update_user_attributes,
       Resolution.cleanup_events(enemy_ship, 'destroyed'),
       Resolution.recycle_mission],
  
    :failure_callbacks =>
      [Resolution.update_user_attributes,
       Resolution.cleanup_events(enemy_ship, 'destroyed'),
       Resolution.recycle_mission]

See the Omega API for complete list of Missions DSL methods.

## Scheduling Events

The Missions subsystem also allows privileged users to setup one-time or repeating events to trigger any custom logic.

For example, the following uses the omega dsl to schedule a repeating event where a random asteroid is picked and populated with random resources:

  event = Missions::Events::PopulateResource.new :id =>  'populate-resources',
            :from_resources => Omega::Resources.all_resources,
            :from_entities  => athena.asteroids

  schedule_event 6000, event
 # The Big Picture ## Retrieving Stats

High level simulation statistics and user ranking mechanisms (eg leaderboard) can be retrieved by invoking RJR methods in the 'stats' subsystem.

Currently there are no custom DSL methods to do so (feel free to file a feature request or PR if you'd like to see it!) but the DSL does provide an easy mechanism which to invoke generic rjr requests against the configured transport like so:

  stat1 = invoke 'stats::get', 'users_with_most',   'kills'
  stat2 = invoke 'stats::get', 'systems_with_most', 'entities'

Stats are very easy to add (see the Stats Registry for details) and can be used for any number of application including diagnostic tools, custom & filtered views onto the universe (with their own permissions), badges, and more.

# Interacting With Your Universe ## Command Line Clients

Omega provides many various command line clients which can be used to query and manipulate the simulation. See the Clients page for a more detailed listing

## Web Client

The web client is explored in full detail on the Web UI section of the wiki.

## Other Clients

This page covers most of the exist clients for omega but that doesn't mean more can't be written!

Perhaps an Android or iOS client. Or perhaps a desktop client that interfaces with the Occulus Rift. Or something else all togther!
Add a custom footer
Add a custom sidebar
Clone this wiki locally