hump.signal

Signal = require 'hump.signal'

A simple yet effective implementation of Signals and Slots, aka the Observer pattern: Functions can be dynamically bound to signals. When a signal is emitted, all registered functions will be invoked. Simple as that.

hump.signal makes things a little more interesting by allowing to emit all signals that match a Lua string pattern.

Example:

-- in AI.lua
Signal.register('shoot', function(x,y, dx,dy)
    -- for every critter in the path of the bullet:
    -- try to avoid being hit
    for critter in pairs(critters) do
        if critter:intersectsRay(x,y, dx,dy) then
            critter:setMoveDirection(-dy, dx)
        end
    end
end)

-- in sounds.lua
Signal.register('shoot', function()
    Sounds.fire_bullet:play()
end)

-- in main.lua
function love.keypressed(key)
    if key == ' ' then
        local x,y   = player.pos:unpack()
        local dx,dy = player.direction:unpack()
        Signal.emit('shoot', x,y, dx,dy)
    end
end

Function Reference

Signal.new()
Returns:A new signal registry.

Creates a new signal registry that is independent of the default registry: It will manage its own list of signals and does not in any way affect the the global registry. Likewise, the global registry does not affect the instance.

Note

If you don’t need multiple independent registries, you can use the global/default registry (see examples).

Note

Unlike the default one, signal registry instances use the colon-syntax, i.e., you need to call instance:emit('foo', 23) instead of Signal.emit('foo', 23).

Example:

player.signals = Signal.new()
Signal.register(s, f)
Arguments:
  • s (string) – The signal identifier.
  • f (function) – The function to register.
Returns:

A function handle to use in Signal.remove().

Registers a function f to be called when signal s is emitted.

Examples:

Signal.register('level-complete', function() self.fanfare:play() end)

handle = Signal.register('level-load', function(level) level.show_help() end)

menu:register('key-left', select_previous_item)
Signal.emit(s, ...)
Arguments:
  • s (string) – The signal identifier.
  • ... (mixed) – Arguments to pass to the bound functions. (optional)

Calls all functions bound to signal s with the supplied arguments.

Examples:

function love.keypressed(key)
    -- using a signal instance
    if key == 'left' then menu:emit('key-left') end
end

if level.is_finished() then
    -- adding arguments
    Signal.emit('level-load', level.next_level)
end
Signal.remove(s, ...)
Arguments:
  • s (string) – The signal identifier.
  • ... (functions) – Functions to unbind from the signal.

Unbinds (removes) functions from signal s.

Example:

Signal.remove('level-load', handle)
Signal.clear(s)
Arguments:
  • s (string) – The signal identifier.

Removes all functions from signal s.

Example:

Signal.clear('key-left')
Signal.emitPattern(p, ...)
Arguments:
  • p (string) – The signal identifier pattern.
  • ... (mixed) – Arguments to pass to the bound functions. (optional)

Emits all signals that match a Lua string pattern.

Example:

-- emit all update signals
Signal.emitPattern('^update%-.*', dt)
Signal.removePattern(p, ...)
Arguments:
  • p (string) – The signal identifier pattern.
  • ... (functions) – Functions to unbind from the signals.

Removes functions from all signals that match a Lua string pattern.

Example:

Signal.removePattern('key%-.*', play_click_sound)
Signal.clearPattern(p)
Arguments:
  • p (string) – The signal identifier pattern.

Removes all functions from all signals that match a Lua string pattern.

Examples:

Signal.clearPattern('sound%-.*')

player.signals:clearPattern('.*') -- clear all signals