Class: Pixiurge::AppInterface

Inherits:
Object
  • Object
show all
Defined in:
lib/pixiurge/app.rb

Overview

This is an interface class that defines all handlers for a Pixiurge application. It's possible to inherit from it but then you must override all handlers and you won't get higher-level application functionality, which you probably want. Instead, inherit from AuthenticatedApp or just App. This class exists primarily for purposes of documentation.

Here is a config.ru that sets up a very basic Pixiurge App:

require "pixiurge"
# require_relative "my_pixiurge_app_file"

# You can also set up normal Rack code here like logfiles or
# EM.error_handler here.

# Instead of Pixiurge::App, you can instantiate a child class here
app = Pixiurge::App.new
app.rack_builder self
app.root_dir __dir__
app.coffeescript_dirs "coffee"
app.static_dirs "static"
app.static_files "bobo.txt"

run app.handler

To detect what's happening with an App, you can add handlers for various sorts of events. You can use the #on_event method to subscribe to an event, or you can inherit from an app class (usually AuthenticatedApp) and add child methods. The name of the event is the same as the method without the "on_" prefix. The event and the methods take the same arguments. Here is an example using the #on_close method:

class MyAppSubtype < Pixiurge::AuthenticatedApp
  def on_close(ws, code, reason)
    # Handler code goes here
  end
end

# Or equivalently...
app = Pixiurge::AuthenticatedApp.new
app.on_event("close") do |ws, code, reason|
  # Handler code goes here
end

You can implement most games by only implementing a straightforward higher-level interface and not directly dealing with authentication, websockets, etc. The high-level handlers assume you are using AuthenticatedApp or have implemented the same functionality. Here are high-level handlers you can implement:

Next are the message handlers that your app can define for the low-level message and socket interface. Keep in mind that higher-level functionality with AuthenticatedApp may depend on existing methods for these, so you should call super as appropriate if you override the methods. This is not a problem if you subscribe to events instead of overriding handler methods, which can be a good reason to use #on_event for these.

  • #on_open - message handler for a newly-opened connection
  • #on_close - connection has been closed
  • #on_error - an error has occurred in the websocket layer
  • #on_message - generic low-level message handler for messages not handled by the app
  • #on_login - called when a user successfully logs in using built-in authentication (AuthenticatedApp only)

And finally there's a low-level websocket message handler you can override, but it doesn't send events via on_event:

  • #handle_message - very low-level message handler, only use it if you're comfortable reading the source code

Some of these handlers may already be defined by AuthenticatedApp, which will require you to call super() appropriately.

The low-level message handlers tend to use websocket objects. A websocket object has a #send(message) method and a #close(code, reason) method. #send normally takes a String, and #close can be called without arguments if you don't know or want to provide a code or reason. For more detail on the Websocket object, see https://github.com/faye/faye-websocket-ruby/blob/master/lib/faye/websocket/api.rb

See Also:

Since:

  • 0.1.0

Instance Method Summary collapse

Instance Method Details

#handle_message(ws, data) ⇒ Object

This handler can be enhanced or overridden by various App subtypes, and will normally dispatch to on_message or other handlers if it can't fully handle a given message itself. If you want to be sure to catch every message for some reason, this can be the method to override to do it. This method has no equivalent event for #on_event.

Parameters:

  • ws (Websocket) —

    The Ruby-Websocket-Driver websocket object

  • data (Hash) —

    Deserialized JSON data sent from the client

Since:

  • 0.1.0



170
171
172
 
# File 'lib/pixiurge/app.rb', line 170

def handle_message(ws, data)
  raise "Do not use AppInterface directly!"
end

#on_close(ws, code, reason) ⇒ void

This method returns an undefined value.

This handler will be called when a websocket connection is closed. It can be used for cleaning up player-related data structures.

Parameters:

  • ws (Websocket) —

    A Websocket-Driver websocket object

  • code (Integer) —

    A Websocket protocol onclose status code (see https://tools.ietf.org/html/rfc6455)

  • reason (String) —

    A reason for the websocket closing

Since:

  • 0.1.0



116
117
118
 
# File 'lib/pixiurge/app.rb', line 116

def on_close(ws, code, reason)
  raise "Do not use AppInterface directly!"
end

#on_error(ws, message) ⇒ void

This method returns an undefined value.

This is called if the websocket has a protocol error.

Parameters:

  • ws (Websocket) —

    A Websocket-Driver websocket object

  • message (String) —

    The error message

Since:

  • 0.1.0



126
127
128
 
# File 'lib/pixiurge/app.rb', line 126

def on_error(ws, message)
  raise "Do not use AppInterface directly!"
end

#on_event(event) { ... } ⇒ void

This method returns an undefined value.

This method allows you to handle one or more events of your choice using a handler of your choice. For the list of events, see Pixiurge::AppInterface. The handler will be called whenever the event occurs, and the block will receive the same arguments that a child method would receive for that event type.

Parameters:

  • event (String) —

    The name of the event, such as "close" or "player_login"

Yields:

  • Your handler for the event in question, which takes event-dependent arguments

Yield Returns:

  • (void)

See Also:

Since:

  • 0.1.0



247
248
249
 
# File 'lib/pixiurge/app.rb', line 247

def on_event(event, &block)
  raise "Do not use AppInterface directly!"
end

#on_login(ws, username) ⇒ void

This method returns an undefined value.

If you inherit from AuthenticatedApp, this handler will be called when a player has successfully logged in. Later handlers will continue passing the websocket object. This handler lets you associate the websocket with a specific player account. If you override this method, make sure to call super() so that the AuthenticatedApp code can implement methods like Pixiurge::AuthenticatedApp#username_for_websocket.

Parameters:

  • ws (Websocket) —

    A Websocket-Driver websocket object

  • username (String) —

    The username for the account

Since:

  • 0.1.0



156
157
158
 
# File 'lib/pixiurge/app.rb', line 156

def (ws, username)
  raise "Do not use AppInterface directly!"
end

#on_message(ws, *args) ⇒ void

This method returns an undefined value.

This handler is for messages that are not automatically handled by your application (e.g. non-auth messages for an AuthenticatedApp.) The message content is sent by the client-side browser code. What user took the action should be checked via the websocket object, which will be the same as the one passed to on_login or on_open.

Parameters:

  • ws (Websocket) —

    A Websocket-Driver websocket object

  • args (Array) —

    All remaining arguments to the method

Since:

  • 0.1.0



140
141
142
 
# File 'lib/pixiurge/app.rb', line 140

def on_message(ws, *args)
  raise "Do not use AppInterface directly!"
end

#on_open(ws) ⇒ void

This method returns an undefined value.

This handler will be called when a new websocket connection is made. At this point we don't know what player/account the connection is for, nor very much else about it. If you are inheriting from AuthenticatedApp, the #on_login handler will later associate this connection with an account username.

Parameters:

  • ws (Websocket) —

    A Websocket-Driver websocket object

Since:

  • 0.1.0



103
104
105
 
# File 'lib/pixiurge/app.rb', line 103

def on_open(ws)
  raise "Do not use AppInterface directly!"
end

#on_player_action(username, action_name, *args) ⇒ void

This method returns an undefined value.

This event means a player has sent a message from their browser to your application.

Parameters:

  • username (String) —

    The player's registered username

  • message_type (String) —

    The type of the message

  • args (Array) —

    Arguments sent along with this message

See Also:

Since:

  • 0.1.0



206
207
208
 
# File 'lib/pixiurge/app.rb', line 206

def on_player_action(username, action_name, *args)
  raise "Do not use AppInterface directly!"
end

#on_player_create_body(username) ⇒ void

This method returns an undefined value.

This event means a player has logged into your application and has no current Demiurge item to represent them. Your handler should create a Demiurge item to represent them.

Parameters:

  • username (String) —

    The new player's registered username

See Also:

Since:

  • 0.1.0



194
195
196
 
# File 'lib/pixiurge/app.rb', line 194

def on_player_create_body(username)
  raise "Do not use AppInterface directly!"
end

#on_player_login(username) ⇒ void

This method returns an undefined value.

This event means a player has logged into your application. Your handler can reflect their logged-in state in their visible presence, if they have one.

Parameters:

  • username (String) —

    The new player's registered username

See Also:

Since:

  • 0.1.0



182
183
184
 
# File 'lib/pixiurge/app.rb', line 182

def (username)
  raise "Do not use AppInterface directly!"
end

#on_player_logout(username) ⇒ void

This method returns an undefined value.

This event means a player has logged out of your application. Your handler can do things like remove their in-game presence if they have one.

Parameters:

  • username (String) —

    The new player's registered username

See Also:

Since:

  • 0.1.0



218
219
220
 
# File 'lib/pixiurge/app.rb', line 218

def on_player_logout(username)
  raise "Do not use AppInterface directly!"
end

#on_player_reconnect(username) ⇒ void

This method returns an undefined value.

This event means a player has reconnected to your application, often by connecting with a new browser. This won't normally require action on your part, but you can react in some way if you wish.

Parameters:

  • username (String) —

    The new player's registered username

See Also:

Since:

  • 0.1.0



231
232
233
 
# File 'lib/pixiurge/app.rb', line 231

def on_player_reconnect(username)
  raise "Do not use AppInterface directly!"
end