extra/game/worlds/worlds-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: audio.engine game.loop help.markup help.syntax kernel math method-chains
   3 ui ui.gadgets.worlds words ;
   4 IN: game.worlds
   5
   6 HELP: game-attributes
   7 { $class-description "Extends the " { $link world-attributes } " tuple class with extra attributes for " { $link game-world } "s:" }
   8 { $list
   9 { { $snippet "tick-interval-micros" } " specifies the number of microseconds between consecutive calls to the world's " { $link tick-game-world } " method by the game loop. An integer greater than zero must be provided." }
  10 { { $snippet "use-game-input?" } " specifies whether the game world should initialize the " { $vocab-link "game.input" } " library for use by the game. False by default." }
  11 { { $snippet "use-audio-engine?" } " specifies whether the game world should manage an " { $link audio-engine } " instance. False by default." }
  12 { { $snippet "audio-engine-device" } " specifies the string name of the OpenAL device the audio engine, if any, should try to open. The default value of " { $link POSTPONE: f } " attempts to open the default OpenAL device." }
  13 { { $snippet "audio-engine-voice-count" } " determines the number of independent voices the audio engine will make available. This determines how many individual audio clips can play simultaneously. This cannot exceed the OpenAL implementation's limit on supported voices." }
  14 { { $snippet "audio-engine-buffer-size" } " determines the size in bytes of the audio buffers the audio engine will stream to the sound card." }
  15 { { $snippet "audio-engine-buffer-count" } " determines the number of buffers the audio engine will allocate per audio clip played." }
  16 } ;
  17
  18 HELP: game-world
  19 { $class-description "A subclass of " { $link world } " that automatically sets up and manages connections to the " { $vocab-link "game.loop" } ", " { $vocab-link "game.input" } ", and " { $vocab-link "audio.engine" } " libraries. It does this by providing methods on " { $link begin-world } ", " { $link end-world } ", and " { $link draw* } ". Subclasses can provide their own world setup and teardown code by adding methods to the " { $link begin-game-world } " and " { $link end-game-world } " generic words."
  20 $nl
  21 "The game-world tuple has the following publicly accessible slots:"
  22 { $list
  23 { { $snippet "game-loop" } " contains the " { $link game-loop } " instance managed by the game world. If the world is inactive, this slot will contain " { $link POSTPONE: f } "." }
  24 { { $snippet "audio-engine" } " contains the " { $link audio-engine } " instance managed by the game world. If the world is inactive, or the " { $snippet "use-audio-engine?" } " slot of the " { $link game-attributes } " object used to initialize the world was false, this slot will contain " { $link POSTPONE: f } "." }
  25 } } ;
  26
  27 HELP: begin-game-world
  28 { $values { "world" game-world } }
  29 { $description "This generic word is called by the " { $link begin-world } " method for " { $link game-world } " subclasses immediately before the game world starts the game loop. If the game world has an " { $link audio-engine } ", it will be initialized and started before " { $snippet "begin-game-world" } " is called." } ;
  30
  31 HELP: end-game-world
  32 { $values { "world" game-world } }
  33 { $description "This generic word is called by the " { $link end-world } " method for " { $link game-world } " subclasses immediately after the game world stops the game loop." } ;
  34
  35 HELP: tick-game-world
  36 { $values { "world" game-world } }
  37 { $description "This generic word is called by the " { $link tick* } " method for " { $link game-world } " subclasses every time the game loop's tick interval occurs." } ;
  38
  39 { game-world begin-game-world end-game-world tick-game-world } related-words
  40
  41 ARTICLE: "game.worlds" "Game worlds"
  42 "The " { $vocab-link "game.worlds" } " vocabulary provides a " { $link world } " subclass that integrates with " { $vocab-link "game.loop" } " and optionally " { $vocab-link "game.input" } " and " { $vocab-link "audio.engine" } " to quickly provide game infrastructure."
  43 { $subsections
  44     game-world
  45     game-attributes
  46 }
  47 "Subclasses of " { $link game-world } " can provide their own setup, teardown, and update code by providing methods for these generic words:"
  48 { $subsections
  49     begin-game-world
  50     end-game-world
  51     tick-game-world
  52 } ;
  53
  54 ABOUT: "game.worlds"