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

@title[#:tag "das-schwarze-auge" #:style '(toc)]{"Das Schwarze Auge"}

@local-table-of-contents[]

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

  Specific procedures for the role playing game system "Das Schwarze
  Auge".

}

@defproc[(d20 [generator pseudo-random-generator? (current-pseudo-random-generator)])
         exact-positive-integer?]{

  Simulates a D20 dice roll and returns a random natural number.
  
  A PRNG to use may optionally be specified via the @scheme[generator]
  argument.

}

@defproc[(simulate-test/attribute [attribute exact-integer?]
                                  [generator pseudo-random-generator? (current-pseudo-random-generator)])
         test-result?]{

  Simulates a plain attribute test. To adjust the difficulty of the
  test, the given @scheme[attribute] value should be modified by
  adding or subtracting some small integer.
  
  You may optionally specify a PRNG to use via the @scheme[generator]
  argument.
  
  This procedure returns a @scheme[test-result] structure with the
  result of the single simulated D20 roll as its @scheme[value].

}

@defproc[(analyze-test/attribute [attribute exact-integer?])
         test-statistics?]{

  Determines the statistical properties of a plain attribute test.
  To adjust the difficulty of the test, the given @scheme[attribute]
  value should be modified by adding or subtracting a small integer.
  
  This procedure returns a @scheme[test-statistics] structure with
  the expected result of a single D20 roll as its
  @scheme[expectation].

}

@defproc[(simulate-test/talent [attribute-0 exact-integer?]
                               [attribute-1 exact-integer?]
                               [attribute-2 exact-integer?]
                               [talent exact-integer?]
                               [generator pseudo-random-generator? (current-pseudo-random-generator)])
         test-result?]{

  Simulates a talent test involving tests of the three given base
  attributes @scheme[attribute-0], @scheme[attribute-1] and
  @scheme[attribute-2]. To adjust the difficulty of the test, the
  given @scheme[talent] value should be modified by adding or
  subtracting some small integer.
  
  You may optionally specify a PRNG to use via the @scheme[generator]
  argument.
  
  This procedure returns a @scheme[test-result] structure with the
  remaining talent points not used in the test as its @scheme[value].

}

@defproc[(analyze-test/talent [attribute-0 exact-integer?]
                              [attribute-1 exact-integer?]
                              [attribute-2 exact-integer?]
                              [talent exact-integer?])
         test-statistics?]{

  Determines the statistical properties of a talent test involving
  tests of the three given base attributes @scheme[attribute-0],
  @scheme[attribute-1] and @scheme[attribute-2]. To adjust the
  difficulty of the test, the given @scheme[talent] value should be
  modified by adding or subtracting some small integer.
  
  This procedure returns a @scheme[test-statistics] structure with the
  expected remaining talent points not used in the test as its
  @scheme[expectation].

}