Event Channel

From FIFE development wiki
Jump to: navigation, search

This article is outdated and needs to be reviewed! Outdated.png

The content of this article is outdated and should be treated as such. We cannot guarantee the accuracy of the information presented here.


Current input manager is seen problematic at least for the following reasons:

  • Context seen hard to understand, seem to be somewhat overlapping with game state concept
  • There cannot be multiple input context active at a time
    • Game events are mapped into keys under certain contexts. In case those events should be propagated into multiple listeners from different context, that is not possible
  • Lua scripts cannot react on events (other than ones coming from widgets)
  • Key modifiers (ctrl, shift..) are not taken into consideration
  • Mouse movement and mouse scroll events are not taken into consideration
  • FIFE events and guichan events are not harmonized(?)
  • enumeration type based events are seen error prone

Current Design

  • input::Manager polls events (e.g. keyboard and mouse) from SDL for further processing
  • input::Manager distributes events to registered listeners.
    • Engine is registered to listen game wide events like quitting the game and toggling the console
    • ViewGameState is registered to view related events, like scrolling the screen
    • Listeners can inform their area of interest with "context" information. This is used as a filtering mechanism in input::Manager. Examples of contexts are "engine" and "map_view".
  • input::Manager pushes all events still to Guichan for further processing
    • Guichan maps SDL events into guichan events (like mousedown, mouseup) that are then handled by the luaGui classes. luaGui maps these events into action events. At the moment only mouse down events are handled this way
    • Luagui calls lua script functions based on function name strings that they have bind to different widgets typically on widget creation time.
  • Scripts set a keymap into input::Manager. Input manager uses this mapping to send correct events to listeners (e.g. mapping arrow-up to move-north). This way view does not have to know about keypresses, it just tells "send me move-north events please".

Input manager design 2007 1.png

Responsibility partitioning

  • InputManager refines SDL events into separated observer interfaces
  • InputManager does the mapping between keys and game events. Mapping information is feed into InputManager by its clients
  • InputManager manages input context. Clients can push and pop contexts into InputManager
  • Clients are responsible for registering, unregistering and listening for specific events
  • Clients are responsible for knowing context names relevant to them
  • Guichan processes raw SDL events on its own
  • Lua scripts must bind their widget action function names on widget tags, that are then used to call the correct function
  • Luagui calls lua scripts based on widget tags

Current Concepts

Input Context

Examples of input contexts in usual games:

  • Game area view (aka map view)
    • Game area can be divided into multiple views, should these be considered as multiple contexts?
  • Start menus
  • In game menu (e.g. inventory, health bar...)
  • Input console

Normally only one context can be active at the time. However in some cases, it might be desirable to post same event into multiple contexts at once (e.g. global graphical theme change or for translucent menus on top of game area(?)). Thus it could be desirable to set multiple contexts active at the same time. Contexts can also be used for filtering the event dispatcher, so that only events relevant to active contexts are processed. There is an "engine context" that can be used to send game wide events, like quitting the game.

SDL Events

FIFE builds on SDL event system. SDL represents all its events in one union. Most relevant events for this analysis are the following

SDL events are processed either via PollEvent, PeepEvents or WaitEvent

Guichan events

The following specifies how guichan handles events [1]. Guichan defines its own event structures in the following way:


Input management can be abstracted as event management (input being one type of event). Thus requirements are also better to be focused on event generic management, instead of just input management. The following lists requirements for the event management:

  • Understandable concepts, difficult spots documented
  • All events (e.g. widget events, key events + their modifiers, mouse events, engine originated events) should be represented in a uniform manner to ease the understanding of the codebase
  • Lua scripts must be able react to events and send events in full, just like C++ code
  • Key modifiers, mouse movement and mouse scroll events must be supported in full
  • Joystick support should be easy to be added into the system
  • "Observer" vs. "event type switching" approach to be decided


Event presentation

  1. Distribute raw SDL events into different modules
    • + Straight forward approach
    • + The way its done currently
    • - Does not map well with guichan approach (guichan events and SDL events must co-exist)
    • - Need to define interfaces e.g. for mouse movement
  2. Use Guichan-like events all over the system, extend where needed with similar interfaces
    • + Harmonized event handling with FIFE and guichan code
    • + Already defined mouse and key listeners & events
    • - Tighter binding against guichan, makes it harder to switch UI framework at later point if required
    • - Requires changes to current model (SDL events vs. Guichan events)
  3. Define FIFE specific event handling
    • + Full flexibility
    • - Separate event handling with FIFE and guichan code
    • - Need to define new interfaces for everything input related
    • - Requires biggest effor

Event mapping

  1. Event mapping is done in listener modules themselves (distribution of raw events)
    • + Most flexible event mapping, e.g. send "GO_NORTH event" only "if UP key is pressed and character is not sleeping"
    • + We probably anyway need to publish raw events to scripts
    • - Change to current model
  2. Event mapping is done in input manager based on mapping tables given by its listeners
    • + Current model, least changes
    • - No way to do complex mappings, even ones with modifiers (ctrl, alt) changes code
    • - Distribution of raw events still probably needed


  • At first sight Guichan event system seems such that it could be used to large extent also in other parts of fife. Perhaps we could do some of the following
    • Use guichan listeners & events directly in fife input manager
    • Inherit our listeners from guichan ones, so that they are extensible by us but still share the common approach
    • In cases where guichan event approach is not sufficient and base classes do not fit, create similar listener & event classes for fife
  • Since fife is a framework for games, simple input mapping seems like no viable option in long term. Thus key mapping could be removed from input manager and that responsibility is pushed into listeners themselves. Listeners could then send the events to other listeners in case that seems right thing to do.
  • If key mapping is removed, context seems to be reasonable to be removed as well. Same effect can be achieved by pushing responsibility into listeners to register / unregister themselves on correct spots.

2007 2 fife event channel class model.jpg