conffile—parse configuration strings

A configuration string defines events, which contain inputs. If an input or event class has a name attribute, it is ‘named’ and is supported in configuration strings (these can be found in inputs_by_name and evts_by_name).

Commenting is shell syntax: the # character indicates that the rest of the line is a comment, unless it is quoted. Whitespace outside of quotes (including blank lines) is ignored.

Events

Each event line is followed by zero or more input lines which are added to that event. Lines are made up of words, and shell-like quoting is supported. An event line follows the form

<type> <name> [args...]

where <type> is the class’s name attribute (a key in evts_by_name) and <name> is the name to give to the event (see EventHandler.add()). args depends on type:

  • button* events take any number of button modes from evts.bmode (DOWN, HELD, etc.). If REPEAT is included, the initial and repeat delays must follow these, in seconds. If DBLCLICK is included, the double-click delay must follow, in seconds
  • other event types take no extra arguments.

Inputs

Input lines follow the form

[event components...] [modifiers...] [scale*]<device> [device ID] [type[:input components...]] [args...]

where:

  • event components are named components of the event this input is inside to attach the input to (see evts.evt_component_names). If none are given, all components of the event are used in order.

  • modifiers is zero or more whitespace-separated modifier definitions. Each is within square [] brackets and is an input definition. The device must match the input (see inputs.mod_devices), and may be omitted if it is the same. The device ID should be omitted, as it must be the same as the input’s. A modifier may also be one of the names in inputs.mod.

  • scale is required for events of type 'relaxis*' (see RelAxis) and no others (the * in this argument is a literal character).

  • device is the device attribute of the input class, found in inputs_by_name.

  • device ID determines which device to listen for input from, and defaults to True (see Input.device_id). This is only allowed for inputs with device 'pad'. This may also be a device variable (Input.device_var) in <>, eg. '<x>' for variable 'x'.

  • type is the name attribute of the input class, found in inputs_by_name. It may be omitted if the given device has only one possible type.

  • input components defines the components of the input to use as a comma-separated string of indices. The number given must match up with event components, and the default is all components of the input, in order.

  • args depends on device and type:

    • kbd key, mouse button and pad * take a key/button ID. As well as number identifiers, keys may be Pygame names (without the K_ prefix) and mouse buttons may be names in inputs.mbtn.
    • if the event is an axis or a button, RelAxisInput subclasses take a boundary argument giving the maximum displacement of the axis from 0.
    • if the event is a button, AxisInput and RelAxisInput subclasses take thresholds arguments down and up, giving the point at which the button is triggered and released.

    These are taken by the input classes, so see their documentation for more details.

Examples

This defines a number of input methods for a 'walk' event:

axis walk
   neg kbd LEFT
   pos kbd RIGHT
   # WASD
   neg kbd a
   pos kbd d
   neg pos pad axis 0
   # axis value depends on mouse position
   neg pos mouse axis:0,1 100

The following defines tile-like movement (also useful for menus).

button4 move DOWN REPEAT .3 .2
    left kbd LEFT
    right kbd RIGHT
    up kbd UP
    down kbd DOWN
    # recall that .6 .4 are axis toggle thresholds
    left right pad axis 0 .6 .4
    up down pad axis 1 .6 .4

# hold a button to speed up
button4 move_fast DOWN REPEAT .2 .1
    left [CTRL] kbd LEFT
    right [CTRL] kbd RIGHT
    up [CTRL] kbd UP
    down [CTRL] kbd DOWN
    # modifier might be a shoulder button or something
    left right [button 4] pad axis 0 .6 .4
    up down [button 4] pad axis 1 .6 .4

This might be useful for moving a cursor (note that the mouse is treated differently than for the axis event above):

relaxis2 move
    left 5*kbd LEFT
    right 5*kbd RIGHT
    up 5*kbd UP
    down 5*kbd DOWN
    left right 5*pad axis 0
    up down 5*pad axis 1
    left right mouse axis:0,1
    up down mouse axis:2,3

RTS-like unit selection:

# drag out a box to select units
button select DOWN UP
    mouse button LEFT

# hold ctrl to drag out another box and add to the selection
button add DOWN UP
    [CTRL] mouse button LEFT

# order selected units to do something
button action DOWN
    mouse button RIGHT

Reference

inputs_by_name = {'kbd': {'key': <class 'engine.evt.inputs.KbdKey'>}, 'mouse': {'axis': <class 'engine.evt.inputs.MouseAxis'>, 'button': <class 'engine.evt.inputs.MouseButton'>}, 'pad': {'axis': <class 'engine.evt.inputs.PadAxis'>, 'button': <class 'engine.evt.inputs.PadButton'>, 'hat': <class 'engine.evt.inputs.PadHat'>}}

A {cls.device: {cls.name: cls}} dict of usable named Input subclasses.

evts_by_name = {'axis': <class 'engine.evt.evts.Axis'>, 'axis2': <class 'engine.evt.evts.Axis2'>, 'button': <class 'engine.evt.evts.Button'>, 'button2': <class 'engine.evt.evts.Button2'>, 'button4': <class 'engine.evt.evts.Button4'>, 'relaxis': <class 'engine.evt.evts.RelAxis'>, 'relaxis2': <class 'engine.evt.evts.RelAxis2'>}

A {cls.name: cls} dict of usable named BaseEvent subclasses.

parse(config) → parsed[source]

Parse an event configuration.

Parameters:config – an open file-like object (with a readline method).
Returns:{name: event} for each named BaseEvent instance.
parse_s(config)[source]

Parse an event configuration from a string.

parse(config) -> parsed

Parameters:config – the string to parse
Returns:{name: event} for each named BaseEvent instance.