Adding better docs to Race and CombatCapableEntity.

lib/LasTres/CombatCapableEntity.pm

@@ -18,6 +18,80 @@ requires(
     'gain_experience', 'get_from_storage',
 );
 
+## IMPLEMENTORS MUST IMPLEMENT
+# sub uuid($self);
+#
+# sub race_string($self);
+#
+# sub nick($self);
+#
+# sub health($self, $health = undef);
+#
+# sub mana($self, $mana = undef);
+#
+# sub born_stats($self);
+#
+# Use a LasTres::Stats object. 
+# (A proper interface should be
+# implemented since there are two
+# different kind of objects that
+# are currently used for this.)
+#
+# sub training_stats($self);
+#
+# Use a LasTres::Stats object.
+# (A proper interface should be
+# implemented since there are two
+# different kind of objects that
+# are currently used for this.)
+#
+# sub experience($self);
+#
+# Can accept also
+# sub experience($self, $experience = undef);
+# but this API should never be used from
+# a function expecting the interface,
+# use gain_experience insteand in
+# those cases, the implementor
+# will decide whenever they level
+# up or not.
+#
+# sub combat_action($self);
+#
+# sub combat_target($self, $combat_target = undef);
+#
+# The implementors are supposed to allow
+# that their combat target is changed 
+# automatically in # case that their 
+# current target is defeated, if
+# you do not want this behavior
+# for your implemetor ensure
+# that the IA in combat_target
+# always chooses a valid and
+# alive target.
+#
+# sub team($self, $team = undef);
+#
+# If you are storing a team
+# and the team is storing
+# you ensure that one of
+# the two references is
+# a weakref or you will
+# get a memory leak.
+#
+# sub gain_experience($self);
+#
+# Some kinds of combat capable
+# entities are not even supposed
+# to level up so this subroutine
+# should do nothing for them.
+#
+# sub get_from_storage($self);
+#
+# If no database or redis update
+# is possible simply do nothing in
+# this method.
+
 ## OVERRIDE
 sub update_location {
 }
@@ -34,6 +108,7 @@ sub append_log_line {
 sub update_team_sprites {
 }
 
+## DO NOT EXTEND NOT SUPPORTED.
 sub race ($self) {
     my $hash;
     $hash = LasTres::Races->new->hash;
@@ -55,6 +130,7 @@ sub update($self) {
     }
 }
 
+## DO NOT EXTEND NOT SUPPORTED. (Yet, may be extensible in the future)
 sub attack ( $self, $enemy_entity ) {
     my $defense = $enemy_entity->resistance;
     my $attack  = $self->strength;
@@ -119,6 +195,7 @@ sub attack ( $self, $enemy_entity ) {
     $enemy_entity->update;
 }
 
+## OVERRIDE (Call super)
 sub on_faint($self) {
     my $team2 = $self->team;
     for my $member ( $team2->combat_members->@* ) {
@@ -146,6 +223,7 @@ sub on_faint($self) {
 
 }
 
+## DO NOT EXTEND NOT SUPPORTED.
 sub level ($self) {
 
     # Floating point trick, works in level 100,
@@ -153,6 +231,7 @@ sub level ($self) {
     return int( $self->experience**( 1 / 3 ) + 0.0000000000001 );
 }
 
+## DO NOT EXTEND NOT SUPPORTED.
 sub max_health ($self) {
     my $races            = LasTres::Races->new;
     my $race             = $self->race;
@@ -165,6 +244,7 @@ sub max_health ($self) {
     return int( $health_scaled + $self->level + 10 );
 }
 
+## DO NOT EXTEND NOT SUPPORTED.
 sub strength ($self) {
     my $races              = LasTres::Races->new;
     my $race               = $self->race;
@@ -177,6 +257,7 @@ sub strength ($self) {
     return int( ( $strength_scaled + 5 ) * 1.1 );
 }
 
+## DO NOT EXTEND NOT SUPPORTED.
 sub speed ($self) {
     my $races           = LasTres::Races->new;
     my $race            = $self->race;
@@ -189,6 +270,7 @@ sub speed ($self) {
     return int( ( $speed_scaled + 5 ) * 1.1 );
 }
 
+## DO NOT EXTEND NOT SUPPORTED.
 sub intelligence ($self) {
     my $races                  = LasTres::Races->new;
     my $race                   = $self->race;
@@ -203,6 +285,7 @@ sub intelligence ($self) {
     return int( ( $intelligence_scaled + 5 ) * 1.1 );
 }
 
+## DO NOT EXTEND NOT SUPPORTED.
 sub resistance ($self) {
     my $races                = LasTres::Races->new;
     my $race                 = $self->race;
@@ -217,6 +300,7 @@ sub resistance ($self) {
     return int( ( $resistance_scaled + 5 ) * 1.1 );
 }
 
+## DO NOT EXTEND NOT SUPPORTED.
 sub max_mana ($self) {
     my $races          = LasTres::Races->new;
     my $race           = $self->race;

lib/LasTres/Race.pm

@@ -11,14 +11,58 @@ use Moo::Role;
 
 requires
   qw/spawn identifier name name_selection description is_playable base_stats experience_drop_base/;
+## IMPLEMENTORS MUST IMPLEMENT
+#
+# sub spawn($self);
+#
+# Must return a LasTres::Location or
+# undef, only needed for PJ races.
+# 
+# sub identifier($self);
+#
+# Must return a unique string across
+# races.
+# 
+# sub name($self);
+#
+# Must return a string.
+# 
+# sub name_selection($self);
+#
+# Must return an string, can be an empty one,
+# this is the name shown in the pj creation,
+# so it is unneeded in non pj races, but not
+# implementing it will result in a error.
+#
+# sub description($self);
+#
+# A string must be returned.
+#
+# sub is_playable($self);
+#
+# If true value a pj can be created of this
+# race, otherwise you cannot create
+# a PJ of this race.
+#
+# sub base_stats($self);
+#
+# A LasTres::Stats object must be
+# returned.
+#
+# sub experience_drop_base($self);
+# 
+# A number greater than 0 must be returned.
+# Otherwise you will trigger undefined
+# behavior.
 
+## DO NOT EXTEND NOT SUPPORTED.
 sub hash ($self) {
     return {
         identifier     => $self->identifier,
         name           => $self->name,
         name_selection => $self->name_selection,
         description    => $self->description,
-        is_playable    => $self->is_playable,
+        is_playable    => !!$self->is_playable,
     };
 }
 1;