NAME
Physics::Balls::Outcome - what a strike did
VERSION
Version 0.06
SYNOPSIS
my $out = $strike->play($world, \@layout);
my $first = $out->first(0); # the ball the cue ball met first, or undef
my @pots = @{ $out->holed }; # [id, pocket, t] in time order
my $rest = $out->rest; # [id, x, y] for every ball in play
my $segs = $out->segments->{0}; # the cue ball's trajectory, segment by segmentDESCRIPTION
The record of one shot. events is every event in time order as [t, kind, a, b]: roll and stop for one ball, ball for two, wall and nose with the wall or nose index, pot with the pocket number, and adjust for the struck ball when the shot carried one. A rules module reads first contact, cushions after contact and pots in order straight off it. down (0.04) is every body that passed its kind's vfall and left play, [id, x, y, t] in time order, where it lay in hundredths of a millimetre and when; such a body is in neither rest nor holed. peak is every body's peak speed over the shot, by id, in metres per second: the number a pinfall rule reads. segments is the trajectory a client plays back, per ball id, each [t0, dur, px, py, vx, vy, ax, ay] in metres and seconds, so a position at time t within a segment is p0 + v (t - t0) + a (t - t0)^2 / 2. A curving ball's trajectory is many short segments; a client plays them exactly as it plays a straight ball's, because each one is still that parabola.
ATTRIBUTES
t
Simulated seconds until the last ball stopped.
n
Events processed.
error
Undef, or events or time when the engine gave up; an outcome with an error is still returned so a caller can see how far it got.
events
rest
holed
segments
energy
Mass-weighted (per unit mass when every body is the default kind), after the strike and after every event, when the strike was traced; else empty.
down
peak
As described above.
kinded
True when the world the shot was played on declares a kind with a size, a mass, a friction or a down threshold of its own; then to_payload carries down and peak.
shot
The shot that produced this.
METHODS
message
A sentence for error, or the empty string.
adjusted_at
The time the struck ball crossed the shot's adjust line, or undef when the shot carried no adjust or the ball never reached the line.
first
my $other = $out->first($id);The first ball $id met, or undef when it met a wall, a nose or a pocket first or nothing at all.
walls_touched
The wall and nose events for a ball.
potted
my $h = $out->potted($id);The [id, pocket, t] row, or undef.
downed
my $d = $out->downed($id);The [id, x, y, t] row of a body that went down, or undef.
peak_of
my $v = $out->peak_of($id);A body's peak speed over the shot.
contacts
The events that are contacts, without the roll, stop, adjust and down transitions.
to_payload
The hash a game stores and a client plays back: engine, t, n, error, events, rest, holed, segments, and down and peak when the world is kinded; a pool payload is what it always was.