/ 
Games-3D-0.10
River stage zero No dependents
/ Games::3D::Thingy

NAME

Games::3D::Thingy - base class for virtual and physical 3D objects

SYNOPSIS

package Games::3D::MyThingy;

use Games::3D::Thingy;
require Exporter;

@ISA = qw/Games::3D::Thingy/;

sub _init
  {
  my ($self) = shift;

  # init with arguments from @_
  }

# override or add any method you need

EXPORTS

Exports nothing on default.

DESCRIPTION

This package provides a base class for "things" in Games::3D. It should not be used on it's own.

METHODS

These methods need not to be overwritten:

new()
my $thingy = Games::3D::Thingy->new(@options);
my $thingy = Games::3D::Thingy->new( $options ); # hash ref w/ options

Creates a new thing.

container()
print $thing->container();

Return the container this thing is contained in or undef for none.

insert()
$thing->insert($other_thing);

Insert the other thing into thing, if possible. Returns undef for not possible (thing does not fit, container full etc), or $thing.

remove()
$container = $thing->inside();			   # get container
$container->remove($thing) if defined $container;  # remove now

# or easier:
$thing->remove();		# if inside container, remove me

Removes the thing from it's container.

See also insert().

is_active()
$thingy->is_active();

Returns true if the thingy is active, or false for inactive.

activate()
$thingy->activate();

Set the thingy to active. Newly created ones are always active.

deactivate()
$thingy->deactivate();

Set the thingy to inactive. Newly created ones are always active.

Inactive thingies ignore signals or state changes until they become active again.

id()

Return the thingy's unique id.

name()
print $thingy->name();
$thingy->name('new name');

Set and/or return the thingy's name. The default name is the last part of the classname, uppercased, preceded by '#' and the thingy's unique id.

is()
$thingy->is('dead');

Returns the flag as 1 or 0. The argument is the flag name.

make()
$thingy->make($flag);
$thingy->make('dead');

Sets the flag named $flag to 1.

is_$name()
print "dead!" if $thingy->is_dead();
$thingy->is_dead(0);			# let it live again

Sets the flag named $name to 1 or 0, if no argument is given, returns simple the state of the flag. Of course, the flag has to exist.

state
print "ON " if $thingy->state() == STATE_ON;
$thingy->state(STATE_OFF);
$thingy->state(STATE_FLIP);

Returns the state of the thing. An optional argument changes the object's state to the given one, and sends the newly set state to all outputs (see add_output().

signal()
$link->signal($input_id,$signal);
$link->signal($self,$signal);

Put the signal into the link's input. The input can either be an ID, or just the object sending the signal. The object needs to be linked to the input of the link first, by using link(), or add_input().

add_input()
$thingy->add_input($object);

Registers $object as a valid input source for this object. Does nothing for Thingies and their subclasses, they simple receive and handle signals from everyone. Important for Games::3D::Link, though.

Do not forget to also register the link $link as output for $object via $object-add_output($link);>. It is easier and safer to just use link() from Games::3D::Link, though.

add_output()
$thingy->add_output($destination);

Registers $object as an output of this object, e.g. each signal the object generateds will also be sent to the destinationt.

If the target of the output is not a Thingy or a subclass, but a Games::3D::Link object, do not forget to also register the object $thingy as input for $destination via $destination-add_input($object);>.

In short: If you want to simple link two objects, just register the second object as output on the first. If you want to link two objects (ore even more) in more complex ways, use link().

link()
$link = $object->link($different_object);

Links the object to a different object by creating an intermediate link object. Returns the reference to that link object.

It is possible to link the object to itself, however, this makes only sense when using delayed, inverted, or otherwise limited (like one-shot) links. Otherwise you create a signal endless-loop, which will take an eternity or two to resolve.

Here is an example, that turns the object automatically off two seconds after it was turned on:

$link = $object->link($object);
$link->delay(2000);
$link->fixed_output(SIGNAL_OFF);
$link->fixed_input(SIGNAL_ON);

Note that without that last line, turning $object would cause another off signal to be send after two more seconds, which is not neccessary. Here is an example of an object that flips it self on and off in randomized 2 second intervalls:

$link = $object->link($object);
$link->delay(2000,500);
$link->fixed_output(SIGNAL_FLIP);

Note that each flip signal will start the next flip signal.

output()
$thingy->output($source,$signal);

Sends the signal $signal to all the outputs that were registered with that thingy and tells the receiver that the signal came from $source. Example to send one signal from the thingy itself (instead of relaying it):

$thingy->output($thingy->{id}, SIGNAL_ON);
del_output()
$thingy->del_output( $listener );

Call to remove $listener from the list of outputs from $thingy.

del_input()
$thingy->del_input( $listener );

Call to remove $listener from the list of inputs from $thingy.

as_string()
$thingy->as_string();

Return this thingy as string.

event()
$thingy->event($src,$event);

When an event (frob, use, kill etc) occurs, this routine handles it.

get()
inputs()
kill()
$thingy->kill();

Sends the thingy itself a KILL signal, then annnounced to all linked things the death of the thingy. Unlinks all inputs and outputs, and then removes the thingy from the world it resided in.

new_flag()
$thingy->new_flag($name,$value);

Creates a new flag with the given name and value and creates an accesssor for it.

outputs()
my @outputs = $thingy->outputs();

Returns a list of all connected outputs of this thingy.

unlink()
$thingy->unlink();

Unlink all inputs and outputs from ourself.

update()
$thingy->update($tick);

If this thingy is going from state A to state B, interpolate values based upon current time tick. If reached state B, disable interpolation, and send a signal. Returns 1 while still in transit, 0 when the target state is/was reached.

AUTHORS

(c) 2002 - 2004, 2006 Tels <http://bloodgate.com/>

SEE ALSO

Games::3D, Games::Irrlicht.