/ 
Games-3D-0.04
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. Can export signal and state names like:

SIGNAL_ON SIGNAL_UP SIGNAL_OPEN
SIGNAL_OFF SIGNAL_CLOSE SIGNAL_DOWN
SIGNAL_FLIP

STATE_ON STATE_UP STATE_OPEN
STATE_OFF STATE_CLOSED STATE_DOWN
STATE_FLIP

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:

$thingy->output($thingy->{id}, SIGNAL_ON);
load()
$thingy->load($baseclass,$file,$difficulty_level);

This loads a file and reads the class and object definitions in this file. The classes and objects are then constructed as subcalsses of $baseclass as they are read in. This basically pullsin the entire object hirarchy plus all the objects, although it make sense to keep them in two seperate files and load first the hirarchy, then the objects:

$thingy->load('Games::3D::Object','hirarchy.txt');
$world = $thingy->load('Games::3D::Object','world.txt');
$level = $thingy->load('Games::3D::Object','level00.txt',1);

The first line loads the hirachy (this doesn't contain any objects, so we discard the return value, although it might be safer to check for stray objects), then loads all the basic world objects (like: player, camera, quests etc and constructs them), and then it loads level 0, and constructs all the objects from there. The difficulty level is set to 1, meaning any object that is defined not to appear in level 1 (like: 1 means Easy, and a certain blocking door is not there in Easy, but only in Hard and Expert) will not be constructed in the first place. This is faster than constructing them, and then throwing them away.

_construct()
$thingy->_construct($baseclass,$hash);

This is called by load() for each object or class to be constructed.

AUTHORS

(c) 2002, 2003, Tels <http://bloodgate.com/>

SEE ALSO

Games::3D, SDL:App::FPS, SDL::App and SDL.