Superclass of all "standard" light sources: torches, lanterns,
campfires, etc. Basically anything whose sole purpose in life
is to be a light source can extend from this class to get features
like turning on & off, modifying its description, having fuel
types and being refuelable, etc. All this behavior is controlled
by properties examined by Lamp.class.
Note: the code for emitting light is in
wyvern.lib.properties.MovableLightSource.class. MovableLightSource
is an intelligent property that you can add to any GameObject to
make it emit light. However, MovableLightSource doesn't give you
the ability to turn its target object on & off, and it doesn't
consume any fuel. To get that behavior you have to use Lamp.class.
If you can't extend Lamp (e.g. you want a refuelable magical sword),
you'll have to cut & paste the Lamp code. Eventually we'd like
to encapsulate fuel consumption into another intelligent property.
Properties for configuring Lamps:
can-turn-on: lamp can be turned on (default "light ")
can-turn-off: lamp can be turned off (default ("extinguish ")
turn-on-cmd: command to use to light it, e.g. "light", "ignite"
turn-off-cmd: command to use to extinguish it, e.g. "extinguish", "snuff"
fuel-type: a string indicating the type of fuel the light
takes, e.g. "wood". Default: none - the source has
no fuel supply and never runs out.
burn-rate: an integer specifying how frequently (in millis)
to deduct fuel-units from the lamp's fuel supply.
fuel-units: how many units to deduct each time the burn-rate
timer expires. Default: 1.
fuel-level: how much fuel the source currently has in it.
max-fuel: the maximum number of fuel units the lamp can hold.
low-msg: a message to display when the lamp is low on fuel.
Default: no message is displayed.
out-msg: a message to display when the lamp runs out of fuel.
Default: no message is displayed.
dead-msg: a message to display when you try to light it when out of fuel.
Default: no message is displayed.
low-level: specifies the low-level threshold where a warning
is issued and the intensity may be reduced.
low-fuel-int: the intensity level to give the lamp's light
source when the fuel reaches the "low" point, if specified.
When the lamp is out of fuel, intensity is always zero.
on: specifies that the lamp is initially ON. If fuel-level
is zero, the lamp will turn off when it's constructed.
off: specifies that the lamp is initially OFF. This is
the default, unless the lamp can't be turned off.
intensity: base intensity of the light source - this property
is transferred to the LightSource property.
light: the LightSource property to use. If none is specified,
a MovableLightSource will be used.
on-image: image to use when the lamp is turned on. If not
specified, doesn't change image when turned on.
off-image: image to use when the lamp is turned off. If not
specified, doesn't change image when turned off.
on-animated: if true, sets the lamp animated when it's on
Any object in the game can be used as fuel; it simply has to
have the "fuel-source" property. For instance, a flask of oil
would have "fuel-source oil" set, making it match any lamp that
requires "oil" as its fuel-type. A fuel source object also has
to have a "fuel-amount" int property (default: 0), and fueling
a lamp with the fuel source deducts up to the maximum amount
the lamp can take from the fuel source's amount.
time_
Marks when our last timer was set - used when the source is
turned off to compute how much fuel to consume, to prevent
people from turning it off & on between timer intervals to keep
the fuel from being consumed.
apply(Commandable agent)
Called by the ApplyCommand when the agent performs "apply".
boolean
belowLowFuelThreshold()
Returns true if our fuel-level is currently below the
int "low-level" threshold property, such that the lamp's
intensity will be diminished.
boolean
canTurnOff()
Returns true if it has the "can-turn-off" property.
boolean
canTurnOn()
Returns true if it has the "can-turn-on" property.
Marks when our last timer was set - used when the source is
turned off to compute how much fuel to consume, to prevent
people from turning it off & on between timer intervals to keep
the fuel from being consumed.
Constructor Detail
Lamp
public Lamp()
Method Detail
initialize
public void initialize()
Adds class-default properties. Our archetype properties
have already been added by now, so we can check them to see
what the user expects of us. (Fuel, on/off, etc.)
Figure out whether we're on or off initially. If we
burn fuel, start a fuel timer.
The logic for determining if we're on is as follows:
Check if there's an "on" or "off" property that
overrides the other settings.
If we use fuel, and we have no fuel, start OFF.
If we can be turned on, but not off, start OFF.
If we can be turned off, but not on, start ON.
If we can be turned on and off, start OFF.
If can-turn-on and can-turn-off are both unspecified,
assume we can't do either, and start ON.
If we're ON and we have fuel, start fuel timer.
If we're ON, make sure we have a LightSource property to
make us radiate. (Both of these are handled by turnOn()).
toggleState
public void toggleState()
Turn from on to off, or off to on, provided this is possible.
public boolean knowsCommand(java.lang.String command)
Returns true if we want to handle the command. We have to
check the arguments carefully to make sure we're not
accidentally handling something that's not for us.
initial - an event encapsulating the initial command
Returns:
a CommandEvent with all the properties of the event.
The first property is "type", whose value is a string with
one of the following values: "turn-on" if the lamp is being
turned on, "turn-off" if the lamp is being extinguished, or
"refuel" if the lamp is being refueled.
The next property is "cmd", whose value is a string set to
the full text of the command for lighting, extinguishing or
refueling the lamp. Examples: "light", "turn on", "turn off".
wyvern.kernel.properties.PList