#lang scribble/doc
@(require scribble/manual
          (for-label "../common.ss"))

@title[#:tag "common" #:style '(toc)]{Common Definitions}

@local-table-of-contents[]

@defmodule[(planet "common.ss" ("murphy" "rpg-utils.plt" 1 0))]{

  The common module contains support for dice rolls, functions useful
  when computing statistics and some structure definitions.

}

@defproc[(make-dice [sides exact-positive-integer?] [cumulative? any/c])
         (->* ()
              (pseudo-random-generator?)
              exact-positive-integer?)]{

  Creates a dice with the specified number of @scheme[sides] and
  optionally with accumulating behaviour, if @scheme[cumulative?]
  is not @scheme[#f].
  
  A cumulative dice is rerolled whenever the result of a roll was
  equal to the number of its sides. The results of multiple (re-)rolls
  are summed up.
  
  Returns a procedure of one optional argument that simulates a dice
  roll. If present, the argument to the die procedure specifies the
  PRNG to use. By default the value of
  @scheme[(current-pseudo-random-generator)] is used.

}

@defproc[(fact [n exact-nonnegative-integer?])
         exact-positive-integer?]{

  Computes the factorial of a natural number @scheme[n]. The result
  of this procedure is an exact number. If @scheme[(eqv? n 0)], the
  procedure returns @scheme[1].

}

@defstruct[test-result ([successful? boolean?]
                        [critical? boolean?]
                        [value any/c])]{

  Represents the result of a simulated test in a role playing game.
  The flags @scheme[successful?] and @scheme[critical?] determine
  the obvious properties of the outcome.
  
  The meaning of the @scheme[value] depends on the rule system and
  potentially on the type of the test.

}

@defstruct[test-statistics ([successful (real-in 0 1)]
                            [critical (real-in 0 1)]
                            [expectation any/c])]{

  Represents the result of a statistical analysis for a test in a
  role playing game. The fields @scheme[successful] and
  @scheme[critical] correspond to the similarly named flags in
  a @scheme[test-result] and contain the probabilities that these
  flags would be set in a simulated result.
  
  The @scheme[expectation] field contains the expected most likely
  value of the @scheme[value] in a simulated test result.

}