From 5ec0f9fac7577daddb50e2780c5cfe839ee5ebb1 Mon Sep 17 00:00:00 2001 From: Viktor Lidholt Date: Wed, 23 Sep 2015 15:34:06 -0700 Subject: [PATCH] Adds documentation and cleans up code --- skysprites/lib/action_spline.dart | 12 ++++++++++ skysprites/lib/constraint.dart | 39 +++++++++++++++++++++++++++++++ skysprites/lib/label.dart | 6 ++++- skysprites/lib/node.dart | 5 ++++ skysprites/lib/util.dart | 28 +++++++++++++++++----- 5 files changed, 83 insertions(+), 7 deletions(-) diff --git a/skysprites/lib/action_spline.dart b/skysprites/lib/action_spline.dart index 6f7fcf4da..1d0e2d105 100644 --- a/skysprites/lib/action_spline.dart +++ b/skysprites/lib/action_spline.dart @@ -17,13 +17,25 @@ Point _cardinalSplineAt(Point p0, Point p1, Point p2, Point p3, double tension, return new Point(x, y); } +/// The spline action is used to animate a point along a spline definied by +/// a set of points. class ActionSpline extends ActionInterval { + + /// Creates a new spline action with a set of points. The [setter] is a + /// callback for setting the positions, [points] define the spline, and + /// [duration] is the time for the action to complete. Optionally a [curve] + /// can be used for easing. ActionSpline(this.setter, this.points, double duration, [Curve curve]) : super(duration, curve) { _dt = 1.0 / (points.length - 1.0); } + /// The callback used to update a point when the action is run. final Function setter; + + /// A list of points that define the spline. final List points; + + /// The tension of the spline, defines the roundness of the curve. double tension = 0.5; double _dt; diff --git a/skysprites/lib/constraint.dart b/skysprites/lib/constraint.dart index 5c21d7816..2edb9b0c8 100644 --- a/skysprites/lib/constraint.dart +++ b/skysprites/lib/constraint.dart @@ -1,9 +1,23 @@ part of skysprites; +/// A constraint limits or otherwise controls a [Node]'s properties, such as +/// position or rotation. Add a list of constraints by setting the [Node]'s +/// constraints property. +/// +/// Constrains are applied after the update calls are +/// completed. They can also be applied at any time by calling a [Node]'s +/// [applyConstraints] method. It's possible to create custom constraints by +/// overriding this class and implementing the [constrain] method. abstract class Constraint { + /// Called before the node's update method is called. This method can be + /// overridden to create setup work that needs to happen before the the + /// node is updated, e.g. to calculate the node's speed. void preUpdate(Node node, double dt) { } + /// Called after update is complete, if the constraint has been added to a + /// [Node]. Override this method to modify the node's property according to + /// the constraint. void constrain(Node node, double dt); } @@ -19,10 +33,17 @@ double _dampenRotation(double src, double dst, double dampening) { return src + delta; } +/// A [Constraint] that aligns a nodes rotation to its movement. class ConstraintRotationToMovement extends Constraint { + /// Creates a new constraint the aligns a nodes rotation to its movement + /// vector. A [baseRotation] and [dampening] can optionally be set. ConstraintRotationToMovement({this.baseRotation: 0.0, this.dampening}); + /// The filter factor used when constraining the rotation of the node. Valid + /// values are in the range 0.0 to 1.0 final double dampening; + + /// The base rotation will be added to a the movement vectors rotation. final double baseRotation; Point _lastPosition; @@ -43,11 +64,23 @@ class ConstraintRotationToMovement extends Constraint { } } +/// A [Constraint] that rotates a node to point towards another node. The target +/// node is allowed to have a different parent, but they must be in the same +/// [SpriteBox]. class ConstraintRotationToNode extends Constraint { + /// Creates a new [Constraint] that rotates the node towards the [targetNode]. + /// The [baseRotation] will be added to the nodes rotation, and [dampening] + /// can be used to ease the rotation. ConstraintRotationToNode(this.targetNode, {this.baseRotation: 0.0, this.dampening}); + /// The node to rotate towards. final Node targetNode; + + /// The base rotation will be added after the target rotation is calculated. final double baseRotation; + + /// The filter factor used when constraining the rotation of the node. Valid + /// values are in the range 0.0 to 1.0 final double dampening; void constrain(Node node, double dt) { @@ -71,7 +104,13 @@ class ConstraintRotationToNode extends Constraint { } } +/// A [Constraint] that constrains the position of a node to equal the position +/// of another node, optionally with dampening. class ConstraintPositionToNode extends Constraint { + /// Creates a new [Constraint] that constrains the poistion of a node to be + /// equal to the position of the [targetNode]. Optionally an [offset] can + /// be used and also [dampening]. The targetNode doesn't need to have the + /// same parent, but they need to be added to the same [SpriteBox]. ConstraintPositionToNode(this.targetNode, {this.dampening, this.offset: Offset.zero}); final Node targetNode; diff --git a/skysprites/lib/label.dart b/skysprites/lib/label.dart index 673a30d6c..be515e859 100644 --- a/skysprites/lib/label.dart +++ b/skysprites/lib/label.dart @@ -1,7 +1,9 @@ part of skysprites; +/// Labels are used to display a string of text in a the node tree. To align +/// the label, the textAlign property of teh [TextStyle] can be set. class Label extends Node { - + /// Creates a new Label with the provided [_text] and [_textStyle]. Label(this._text, [this._textStyle]) { if (_textStyle == null) { _textStyle = new TextStyle(); @@ -10,6 +12,7 @@ class Label extends Node { String _text; + /// The text being drawn by the label. String get text => _text; set text(String text) { @@ -19,6 +22,7 @@ class Label extends Node { TextStyle _textStyle; + /// The style to draw the text in. TextStyle get textStyle => _textStyle; set textStyle(TextStyle textStyle) { diff --git a/skysprites/lib/node.dart b/skysprites/lib/node.dart index 1ce3a0051..9d51195a9 100644 --- a/skysprites/lib/node.dart +++ b/skysprites/lib/node.dart @@ -78,6 +78,8 @@ class Node { List _constraints; + /// A [List] of [Constraint]s that will be applied to the node. + /// The constraints are applied after the [update] method has been called. List get constraints { return _constraints; } @@ -87,6 +89,9 @@ class Node { if (_spriteBox != null) _spriteBox._constrainedNodes = null; } + /// Called to apply the [constraints] to the node. Normally, this method is + /// called automatically by the [SpriteBox], but it can be called manually + /// if the constraints need to be applied immediately. void applyConstraints(double dt) { if (_constraints == null) return; diff --git a/skysprites/lib/util.dart b/skysprites/lib/util.dart index 19c2151e7..0cb740cd7 100644 --- a/skysprites/lib/util.dart +++ b/skysprites/lib/util.dart @@ -5,18 +5,22 @@ math.Random _random = new math.Random(); // Random methods +/// Returns a random [double] in the range of 0.0 to 1.0. double randomDouble() { return _random.nextDouble(); } +/// Returns a random [double] in the range of -1.0 to 1.0. double randomSignedDouble() { return _random.nextDouble() * 2.0 - 1.0; } +/// Returns a random [int] from 0 to max - 1. int randomInt(int max) { return _random.nextInt(max); } +/// Returns either [true] or [false] in a most random fashion. bool randomBool() { return _random.nextDouble() < 0.5; } @@ -54,9 +58,13 @@ class _Atan2Constants { final Float64List nnx = new Float64List(size + 1); } +/// Provides convenience methods for calculations often carried out in graphics. +/// Some of the methods are returning approximations. class GameMath { static final _Atan2Constants _atan2 = new _Atan2Constants(); + /// Returns the angle of two vector components. The result is less acurate + /// than the standard atan2 function in the math package. static double atan2(double y, double x) { if (x >= 0) { if (y >= 0) { @@ -85,7 +93,9 @@ class GameMath { } } - static double pointQuickDist(Point a, Point b) { + /// Approximates the distance between two points. The returned value can be + /// up to 6% wrong in the worst case. + static double distanceBetweenPoints(Point a, Point b) { double dx = a.x - b.x; double dy = a.y - b.y; if (dx < 0.0) dx = -dx; @@ -98,20 +108,26 @@ class GameMath { } } + /// Interpolates a [double] between [a] and [b] according to the + /// [filterFactor], which should be in the range of 0.0 to 1.0. static double filter (double a, double b, double filterFactor) { return (a * (1-filterFactor)) + b * filterFactor; } + /// Interpolates a [Point] between [a] and [b] according to the + /// [filterFactor], which should be in the range of 0.0 to 1.0. static Point filterPoint(Point a, Point b, double filterFactor) { return new Point(filter(a.x, b.x, filterFactor), filter(a.y, b.y, filterFactor)); } - static Point lineIntersection(Point p, Point p2, Point q, Point q2) { + /// Returns the intersection between two line segmentss defined by p0, p1 and + /// q0, q1. If the lines are not intersecting null is returned. + static Point lineIntersection(Point p0, Point p1, Point q0, Point q1) { double epsilon = 1e-10; - Vector2 r = new Vector2(p2.x - p.x, p2.y - p.y); - Vector2 s = new Vector2(q2.x - q.x, q2.y - q.y); - Vector2 qp = new Vector2(q.x - p.x, q.y - p.y); + Vector2 r = new Vector2(p1.x - p0.x, p1.y - p0.y); + Vector2 s = new Vector2(q1.x - q0.x, q1.y - q0.y); + Vector2 qp = new Vector2(q0.x - p0.x, q0.y - p0.y); double rxs = cross2(r, s); @@ -124,7 +140,7 @@ class GameMath { double u = cross2(qp, r) / rxs; if ((0.0 <= t && t <= 1.0) && (0.0 <= u && u <= 1.0)) { - return new Point(p.x + t * r.x, p.y + t * r.y); + return new Point(p0.x + t * r.x, p0.y + t * r.y); } // No intersection between the lines