Clients

• JSON-RPC
  • JSON-RPC-API
  • Callback Events
• Web UI
• Command Line Clients
• Omega Ruby API
• Omega Client DSL
• Examples
• Curl
• Other

# JSON-RPC Any language that has a [json-rpc client](http://en.wikipedia.org/wiki/JSON-RPC#Implementations) library can invoke Omega methods easily by sending requests to the [Omega JSON-RPC Interface](#json-rpc-api).

See specific methods for more details regarding parameter lists, errors thrown, and return values.

Note the AGPLv3 applies to the Omega subsystems & components themselves and does not place any restrictions on external software interfacing with it over a network.

##JSON-RPC API The complete Omega JSON-RPC API can be seen [here](https://github.com/movitto/omega/blob/master/API).

Most public methods other than registration / login related ones require an authenticated session potentionally with additional privs ontop of that (specific to the method being invoked and data its being invoked with).

Private methods can only be invoked by internal subsystems or by privileged users.

##CallbackEvents Various methods in the Omega JSON-RPC API register the client to server-side callbacks which will be periodically invoked at intervals specified by the method parameters.

For example invoking "motel::track_movement, <location_id>, " will subscribe the client to notifications whenever the location moves the specified distance.

The client receives these via json-rpc notifications to corresponding callback methods such as "motel::on_movement, , ".

Invoking these methods must be done over an interface which supports persistant connections, for example TCP, Web Sockets, or AMQP. HTTP will not work for these callbacks (currently).

See the JSON-RPC API for server and client side callback methods.

# Web UI Omega includes a full featured Web Frontend based on middleman and three.js. See the Web UI wiki [section](Web-UI) for more details. # Command Line Clients There are many ways to query and control an Omega simulation straight from the command line

• bin/util/omega-cosmos-retrieve Query cosmos galaxies,systems, other entities by id or name
• bin/util/omega-console Interactive Pry based console which to query and manipulate omega entities
• bin/util/omega-monitor Ncurses based interface which to view overall simulation stats which periodically refresh
• bin/util/omega-status Display a slew of debugging information and simulation statistics. Requires the omega-server to be running in debugging mode to work.
• bin/util/omega-mission-assign Assigns a mission to a specified user
• there are plenty of others see the bin/util/ dir for a complete listing
• TODO add others...

# Omega Ruby API Omega provides a full object orientated Ruby client interface which to transparently query and manipulate server side entities through Ruby classes.

Basic usage allows the user to retrieve and store entities, automatically updating them upon server-side state changes, and invoking simple commands remotely.

Advanced features incorporate various algorithms to seek and move to various targets and perform operations such as mining/attacking/construction upon arrival.

See the Client Documentation for complete usage.

# Omega Client DSL Omega also provides a rich dsl which to quickly setup and manipulate simulations from human-friendly scripts.

See the Client DSL Documentation for complete usage.

require 'omega/client/dsl'

login 'admin', 'secret'

galaxy 'Zeus' do |g|
  system 'Athena', 'HR1925', :location => rand_location(:max => SIZE) do |sys|
    asteroid gen_uuid, :location => rand_location(:max => SIZE) do |ast|
      resource :resource => rand_resource, :quantity => 5000
    end
  end
end

user 'player', 'reyalp' do |u|
  role :regular_user
end

ship =
  ship("player-miner1") do |ship|
    ship.type = :mining
    ship.user_id = 'player'
    ship.solar_system = system('Athena')
    ship.location = rand_location(:max => SIZE)
  end

dock(ship.id, station('player-station1').id)
# etc...

# examples/* The omega client interface and dsl are used in various scripts in the examples/ directory. These are all self contained and may be easily copied by the end user and adapted to serve any purpose. # curl Omega can be invoked over curl like so

$ curl -X POST http://localhost:8888 -d \
  '{"jsonrpc":"2.0", "method":"cosmos::get_entities",
    "params":["of_type", "Cosmos::SolarSystem"], "id":"123"}'

  => {"jsonrpc":"2.0","id":"123","result":[{"json_class":"Cosmos::SolarSystem","data":{"name":"..."}}]}

For this example auth has been disabled by setting 'user_perms_enabled' to false in omega.yml. If enabled, a user can send a request to 'users::login' with valid credentials to retrieve a session id.

Set this session id in the json of subsequent rpc requests (at the top level at the same scope as the 'jsonrpc' and 'method' keys) to authenticate them from here on out.

# Other There are many other ways in which to invoke Omega, any mechanism by which JSON-RPC can get to the process case be used to invoked functionality. See [RJR](http://github.com/movitto/rjr) for currently supported transports (**note** some such as ssh tunnels & udp are on the roadmap, feel free to file an issue or pull request if you'd like to see it in sooner)