Home

Intro

Welcome to the community wiki/portal for the Omega Project. Omega is a Universe Simulator which allows the user to setup a full 3D environment containing heirarchies of oriented locations w/ movement strategies and entities mapped to them. The end user can use the tools in the Omega suite to setup a universe of their own or to connect to an existing one via any number of mechanisms.

Architecture

Omega implements a client-server architecture based on JSON-RPC. The server uses RJR to listen for requests over a variety of protocols including TCP, HTTP, Websockets, AMQP, and more. This means JSON-RPC clients written in any language may communicate with Omega (see below ).

omega-server is the server executable which loads the JSON-RPC method definitions before listening on the transport protocols (SIGTERM may be sent to the server process to gracefully terminate it). The server may be configured through a variety of means, see below. Once running the end user may connect to the server via several channels such as the omega client interface and/or dsl, various command line utilities, a rich HTML5 based web frontend, or even just by sending json-rpc requests to the server using Curl.

The Omega Server JSON-RPC API provides full access to various subsystems to query and manipulate universe entities. These subsystems are

• motel: base location tracking
• users: users, sessions, and permissions, implements a full role-based access control system allowing all entities in all other systems to be restricted
• cosmos: cosmos entities (galaxys, systems, planets, etc) mapped to motel locations and the methods to query them
• manufactured: ships, stations, other player controlled entities and methods to query and manipulate them
• missions: high level goals and events which may be assigned to users
• stats: high level simulation statistics
• omega: the glue binding it all together

The Omega project provides many other modules and components for various purposes. See the examples/ directory for many different scripts to setup and seed various universes, simulations, users, and entities, and to manipulate those according to specified algorithms. The omega-console utility is a Pry based console with an Omega client session established on start and the complete client interface available in an interactive manner. The omega-monitor command is a ncurses based interface providing a high level overview of a running simulation. The site directory contains a Middleman based Javascript frontend which a user can use to graphically via a universe and all the entities running in it. See the project repository for a complete list.

Using the simulation

New users who just want to use the simulation may want to check out the Omega instance hosted at omegaverse.info. Click Register in the upper left to create a new account making sure to confirm the registration email, and then login! From here you can use the web interface to view the universe and control the entities which have been created for you (see below)

Running the simulation

The Omega Config Recipe is a good starting resource to see the steps required to install project releases on rpm based systems (deb support coming soon). To use the recipe simply download the bin/omega-bootstrap.sh script and run it as root like so:

$ wget https://raw.github.com/movitto/omega-conf/master/bin/omega-bootstrap.sh
$ chmod +x omega-bootstrap.sh
$ sudo ./omega-bootstrap.sh

The script will take care of installing the necessary components and configuring / starting the necessary services to get everything up and running. From there you can seed an initial universe using the example scripts (see below)

To manually checkout the project from scratch (should work on the latest Fedora and Ubuntu releases):

$ git clone http://github.com/movitto/omega.git
$ cd omega

Install binary dependencies:

$ sudo yum install ruby-devel openssl-devel gcc-c++ make rabbitmq-server libcurl-devel httpd

-or-

$ sudo apt-get install # ...TODO

Install gem dependencies:

$ gem install rjr activesupport em-websocket eventmachine_httpserver em-http-request em-websocket-client amqp pry curb # sudo is not required if --install-dir is set to your users gem home which is suggested to isolate deps (see 'gem environment')
$ gem install json --version 1.7.5

Note due to an issue json version <= 1.7.5 is required. If at this point you have another version (check with 'gem list') uninstall it ('gem install json --version 1.7.7'). This should hopefully be resolved soon.

Startup the rabbitmq AMQP server (this is not required, amqp can be disabled in omega.yml)

$ sudo service rabbitmq-server start

Startup omega:

$ RUBYLIB='lib' ./bin/omega-server

Seeding some data

Omega comes with many example scripts which connect to a running server using a privileged account to create cosmos entities as well as ship and stations, and run those according to certain algorithms. The scripts assume the server is running on localhost at the default port and used the default administrative credentials to login. If Omega has been configured to run elsewhere or to use different credentials (see below) the scripts will need to be modified before they can be used (this is relatively easy as they are self-contained and destination host/port as well as login user/pass are at the top of every script).

To create a universe run any of the examples from the examples/universes directory:

$ ./examples/universes/small.rb
$ ./examples/universes/medium.rb
$ ./examples/universes/complete.rb

To create a new user, run user.rb with the username, password, starting system (assumed to already have been created) and role list like so:

$ ./examples/user.rb Anubis secret Athena regular_user

This will create the user (Anubis in the example) as well as a few entities ships and a station in the specified system (Athena in the example).

A user's ships and stations can be run in accordance to a simple generic algorithm that will mine resources with miners, attack enemies with corvettes, create new ships with factories, etc, like so:

$ ./example/bot.rb Anubis secret

There are many other examples in the examples directory which may be used to create and manipulate data. Furthermore once setup, a server may be queried and manipulated manually by the commands in the bin/util directory

Running the frontend

Omega comes with an optional frontend that can be used to view and manipulate Omega universes right from the web browser. The frontend is built with the Middleman static site generator which process haml and sass temples as well as the Omega javascript client and produces a static site which can be served by any web server (apache, nginx, etc).

To setup the site from a working checkout and running omega-server run:

$ gem install middleman
$ rake site:preview

This will setup a thin web server to server pages, regenerating them as they are modified on the disk (good for testing changes out).

Unfortunately due to cross site scripting restrictions the end-user's web browser will not be able to request data from both the static site as well as from omega-server running on a different port. The server admin can use an webserver such as httpd or nginx to act as a frontend, proxying requests as they arrive to the static site or omega-server. An example httpd config file setting this up can be seen here.

To build the static site in a more permentant fashion, run

$ rake site:build

This will generate the html/js/css and write it to the disk (in the site/build) directory. The server admin may simply drop this folder into their webserver document root to easily / efficiently serve the frontend (a proxy will still be needed for the running omega-server simulation itself)

Getting Help

Issues / bugs with Omega may be filed with the github project tracker.

Otherwise feel free to ping me ('mmorsi' on irc.freenode.net, I often linger in the #omegaverse chatroom) or email me ([email protected]) with project questions, feedback or other discussions.

Entities/Concepts

• location - central component containing coordinates, an orientation, a movement strategy, and optional parent id. Locations with nil parents are assumed to be the root locations of their respective coordinate systems. The Motel server will periodically move / update location's coordinates and orientations in accordance to their movement strategies. Most regular users will only read access to motel locations (also being able to register callbacks to be invokd on updates and such) as creating/updatig locations is done internally by other subsystems as needed

• movement strategy - Several movement strategies including stopped, linear, elliptical movement, rotating, following another location, etc have already been defined. These must reside on the server side and will be periodically invoked to move the locations which they correspond to. Developers / server admins can easily add more strategies to describe any sort of desired movement.

• galaxy/solar system/star/planet/asteroid - The cosmos subsystem describes a physical universe. These entities are mapped to locations running in motel (for the most part all these have a stopped movement strategy though planets move along an elliptical orbit). All entities are read only.

• resource: asteroids may contain resources which may be mined by a mining ship, and transfered to a station to use to construct new entities. Resources will be depleted over time though the server admin may use the mission subsytem to setup periodic events that will populate resources among other things.

• jump gate: These artifacts link solar systems together. Player owned ships withing the trigger distance of a gate will jump to the destination system when the trigger command is issues. Be forewarned though, there might not be a gate back!

• ship/station: Player controlled entities used to move around and manipulate the universe. Ships have movement capabilities within a system as well as the means to mine resource and attack other ships (depending on the class). Ships require the use of jump gates to travel between systems. Stations on the other hand can jump between systems at will but do not have the means to travel within in a system. Manufacturing stations may be used to construct new ships and stations provided they have the resources.

• mission - High level sequence of requirements, objectives, victory conditions, and rewards/penalties which privilged users may create. Any user satisfying a mission's requirement may accept it (provided they are not engaged in another mission at the time) and attempt to complete it. All missions are timed, the user has until the mission's expiration to complete the objectives. If they do so, their stats will be increased, and often a reward is issued.

Using the Interface

Registering

Users may register a new account by clicking the 'Register' link in the main navigation:

A valid username, password, email, and recaptcha answer is required. Once the form is submitted, a confirmation email will be sent to specified address. Clicking on that will finalize the account, allowing the user to login with their credentials

Logging in

Login via the 'Login' link in the main navigation. Only users with confirmed registrations may login.

Once the user logs in the entities they own and systems / galaxies they are in will be available in the page navigation. Click on any item to bring it up in the canvas.

The 'Logout' link will replace the 'Login' link. Sessions will automatically log out if there is no activity for 1 hour.

Viewing Systems / Galaxies

Click on a system or galaxy on the page to bring it up in the canvas. Various entities in the galaxy (system) and in the system (jump gates, stations, ships, asteroids) can be clicked on to interact with furthur.

Viewing Resources

Click on any asteroid to see the mine-able resources which the asteroid contains.

Triggering Jump Gates

Clicking on a jump gate will visually bring up its trigger radius in the viewing area. Any player owned ships within this distance will jump to the destination system once the trigger command is issued.

Viewing a ship

Clicking a ship will bring up its details in a popup. Various ship attributes such as the current position, system, resource and more can be accessed from here. A list of commands which are available for the ship in its given state will be accessible here. Some commands take effect immediately, while others will prompt the user for further parameters.

Mining Resources

The mining command is displayed in the details container of any ship with mining capabilities. Clicking on this brings up all the resources in the area in a popup. Clicking on any of these begins mining that resource with the miner. On the server side the miner will periodically extract a fixed quantity from the resource until its cargo is full or mining cannot otherwise continue.

Moving ships

Clicking on the movement command in any ship container brings up a coordinate selection popup. The user can then specify the location to move the ship and submit the form. The ship will rotate towards the direction of movement, move to the specified location and stop.

Attacking

The attack command is displayed in the details container of any ship with attack capabilities. Clicking on this brings up all the enemy ships in the area in a popup. Clicking on any of these commences the attack. On the server side the attacker will periodically attack the defender, depleting its shield (periodically refreshed by the defender) then its hp, which if it is reduced to 0 results in the defending ship being destroyed. This continues until the defender is destroyed, moves outside the attacker's attack radius, or the attack cannot otherwise continue.

Docking / Undocking

The dock command is displayed for all ships that are not currently docked. Clicking it scans for and displays stations in the vicinity of the ship. Clicking a station docks the ship to it.

The undock command will be displayed for all ships the are docked. Clicking it will undock the ship from the station it is currently docked at.

Transferring Resources

Any entity can transfer resources to another provided the destination is within transfer distance and has space for the resource. Currently the UI only supports transferring on resources from docked ships to the stations they are docked at. Simply click the transfer command with any docked ship selected to transfer all contained resources to the station.

Constructing Entities

Manufacturing stations can construct new ships / stations on demand. Simply click the construct command with a station selected to begin the process. While the resources for the entity are used immediately, construction takes place in stages over time (the user can subscribe to the progress of these if needed). Once it's complete the constructed entity is placed in the vicinty as the manufacturer and is available for use.

Accepting/Completing Missions

Missions can be viewed / acceped by clicking the missions button on the page. The number or missions the current user has completed and failed will be displayed as well as the current active mission or a list of missions the user can accept. Clicking one will bring up mission details and will allow the user to accept it if they so choose.

Editing Account Info

The main navigation allows the user to access their account page. From here they can change their password, view the entities they own, as well as any badges/title which their user may have earned..

The user's avatar will be loaded from the gravatar associated with their email address.

Viewing Stats

The main navigation also allows the user to access overall system stats. Additional stats and debugging interfaces are provided if configured in the omega server. See Configuring the Server below.

Interacting with the simulation

There are many other ways to query and control an Omega simulation other than the Web frontend

bin/util

Many various utilities to server many various purposes

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 bases 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

Omega Client

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 alogrithms 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

Any language that has a json-rpc client library should be able to invoke omega methods easily by sending requests for the Omega JSON-RPC Methods, see specific methods for more details regarding parameter lists, errors thrown, and return values.

#Configuring the Server The omega.yml config file will be read from the following locations upon server startup:

• /etc/omega.yml
• ~/.omega.yml
• ./omega.yml

Options defined in subsequent locations will override former ones. The following options are accepted:

• omega_url: location returned by server which javascript requests will be sent to
• backup_dir: path to directory to write server backups to
• log_level: log verbosity level, set this to 'debug' to the enable server debugging mode (additional debugging json-rpc methods will be defined)
• permenant_users: list of users treated specially
• user_perms_enabled: bool to enabled/disable the permission system (if disabled all users will have access to invoke all methods)
• user_attrs_enabled: bool to enable/disable the attribute system (if disabled all calls to check attribute will yield true, indicating the user has it)
• node_id: identifier of the rjr server node
• node_types: transport types which server should listen on
• amqp_broker: amqp broker to connect to (only for amqp transport)
• tcp_host: host to listen on for tcp connections
• tcp_port: port to listen on for tcp connections
• ws_host: host to listen on for websocket connections
• ws_port: port to listen on for websocket connections
• www_host: host to listen on for www connections
• www_port: port to listen on for www connections
• admin_user/cosmos_rjr_user/manufactured_rjr_user/missions_rjr_user/users_rjr_user/stats_rjr_user: username of various privileged users
• admin_pass/cosmos_rjr_pass/manufactured_rjr_pass/missions_rjr_pass/passs_rjr_pass/stats_rjr_pass: password of various privileged users
• email_enabled: bool toggling if user emails should be sent
• smtp_host: smtp host to connect to send user emails
• smtp_from_address: from address to set on user emails
• recaptcha_enabled: boolean toggling registration recaptcha requirement
• recaptcha_priv_key: recaptcha private key send to recaptcha servers w/ users answer

Furthermore, the server command and other command line utilities / scripts also take and often require parameters. Pass --help to these scripts and/or read the help documentation at the top for detailed usage and specification of these options.

The web frontend may be configured by editing site/source/javascripts/omega/config.js. Here you may specify various parameters such as the Omega server to connect to, options to pass to event subscription methods, and the various resources used to render entities.

#JSON-RPC API The complete Omega JSON-RPC API can be seen here. 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.

#Content The web interface uses a combination of standard html/css as well as three.js to represent and render Omega entities. Thus any mesh, texture, or other resource accepted by three.js is allowed by Omega. There is an easy to use plugin for Blender which allows you to export any model to the supported format. Furthermore instructions and various helper scripts are provided part of the omega-conf project.

#Backups/Restoration Send a SIGUSR1 signal to a running omega-server process to issue a backup command. A new backup file labeled with the current timestamp will be created in the directory configured in omega.yml. Send a SIGUSR2 signal to a running omega-server process to load entities from the latest backup.

The omega-backup and omega-restore utilities do just this, looking up the PID of the running omega-server process in the process table before issuing the corresponding signal.

#Contributing I'd love to accept any contributions / feedback / other. Feel free to use the github issue tracker, this wiki, irc, or just send me an email.

#About Just doing this for fun, want to make the ultimate open source sim.

There's alot more coming, stay tuned for updates!