From 7fe48853acbd376cdd9c701d6d37acc2784d130d Mon Sep 17 00:00:00 2001 From: David Thompson Date: Mon, 23 Jan 2017 21:44:37 -0500 Subject: Add Chickadee manual. --- manuals/chickadee/Kernel.html | 416 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 416 insertions(+) create mode 100644 manuals/chickadee/Kernel.html (limited to 'manuals/chickadee/Kernel.html') diff --git a/manuals/chickadee/Kernel.html b/manuals/chickadee/Kernel.html new file mode 100644 index 0000000..c9d635b --- /dev/null +++ b/manuals/chickadee/Kernel.html @@ -0,0 +1,416 @@ + + + + + +The Chickadee Game Toolkit: Kernel + + + + + + + + + + + + + + + + + + + + +
+

+Next: , Up: API Reference   [Contents][Index]

+
+
+ +

2.1 Kernel

+ +

At the very core of Chickadee, in the (chickadee) module, lies +an event loop. This loop, or “kernel”, is responsible for creating +and managing the game window, dispatching input events, ensuring that +the game is updated at the desired interval, and rendering graphics. +The kernel implements what is known as a “fixed timestep” game loop, +meaning that the game simulation will be advanced by a fixed interval +of time and will never vary from frame to frame, unlike some other +styles of game loops. The appropriately named run-game and +abort-game procedures are the entry and exit points to the +Chickadee kernel. +

+

On its own, the kernel does not do very much at all. In order to +actually respond to input events, update game state, or draw something +to the game window, a hacker with a penchant for game development must +latch onto extension points built into the kernel, called “hooks”, +and specify what action ought to be taken for any given event. For +example, the key-press-hook can be used to respond to the +a key being pressed by swinging the player’s mighty sword. +There are many hooks available, so read on to learn about all of them. +For information about using Guile’s hook API, see See Hooks in GNU Guile Reference Manual. +

+
+
Scheme Procedure: run-game [#:window-title "Chickadee!"]
+

[#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f] + [#:update-hz 60] +Start the event loop. This procedure will not return until +abort-game is called. +

+

The update-hook will be run update-hz times per second. +

+

A new graphical window will be opened with window-width x +window-height as its dimensions, window-title as its +title, and in fullscreen mode if window-fullscreen? is +#t. +

+ +
+
Scheme Procedure: abort-game
+

Stop the currently running Chickadee event loop. +

+ +
+
Scheme Procedure: time
+

Return the current game time in milliseconds. +

+ +
+
Scheme Variable: load-hook
+

A hook that is run once when the event loop boots, before any other +hook is run. This hook is run with zero arguments. +

+
+
(add-hook! load-hook (lambda () (display "hello!\n")))
+
+ +
+ +
+
Scheme Variable: update-hook
+

A hook that is run every time the game simulation should be advanced. +This hook is run with a single argument dt, the fixed timestep +that was configured when the event loop was started, in milliseconds. +

+
+
(add-hook! update-hook (lambda (dt) (display "tick!\n")))
+
+ +
+ +
+
Scheme Variable: before-draw-hook
+

A hook that is run before a frame is rendered. This hook is run with +zero arguments. +

+
+
(add-hook! before-draw-hook (lambda () (display "about to draw!\n")))
+
+ +
+ +
+
Scheme Variable: after-draw-hook
+

A hook that is run after a frame is rendered. This hook is run with +zero arguments. +

+
+
(add-hook! after-draw-hook (lambda () (display "done drawing!\n")))
+
+ +

Combined with before-draw-hook, one can perform a frames per +second calculation to monitor game performance and stability. +

+
+ +
+
Scheme Variable: draw-hook
+

A hook that is run each time a frame should be rendered. This hook is +run with a single argument alpha, a value in the range [0, 1] +which represents how much time has past since the last game state +update relative to the upcoming game state update, as a percentage. +Because the game state is updated independent of rendering, it is +often the case that rendering is occuring between two updates. If the +game is rendered as it was during the last update, a strange +side-effect will occur that makes animation appear rough or +“choppy”. To counter this, the alpha value can be used to +perfrom a linear interpolation of a moving object between its current +position and its previous position. This odd trick has the pleasing +result of making the animation look smooth again, but requires keeping +track of previous state. +

+ +
+
(add-hook! draw-hook (lambda (alpha) (display "<(._.<) \n")))
+
+ +
+ +
+
Scheme Variable: quit-hook
+

A hook that is run when the user clicks the close button on the game +window. This hook is run with zero arguments. +

+
+
(add-hook! quit-hook (lambda () (display "bye!\n")))
+
+ +
+ +
+
Scheme Variable: key-press-hook
+

A hook that is run when a key is pressed on the keyboard. This hook +is run with four arguments: +

+
    +
  1. key: The symbolic name of the “virtual” key that was pressed. +For example: backspace. It’s called a virtual key because the +operating system may map a physical keyboard key to another key +entirely, such as how the author binds the “caps lock” key to mean +“control”. + +
  2. scancode: The symbolic name of the physical key that was +pressed. + +
  3. modifiers: A list of the symbolic names of modifier keys that +were being held down when the key was pressed. Possible values +include ctrl, alt, and shift. + +
  4. repeat?: #t if this is a repeated press of the same key. + +
+ +
+
(add-hook! key-press-hook
+           (lambda (key scancode modifiers repeat?)
+             (display "pressed key: ")
+             (display key)
+             (newline)))
+
+ +
+ +
+
Scheme Variable: key-release-hook
+

A hook that is run when a key is released on the keyboard. This hook +is run with three arguments: +

+
    +
  1. key: The symbolic name of the “virtual” key that was released. + +
  2. scancode: The symbolic name of the physical key that was +released. + +
  3. modifiers: A list of the symbolic names of modifier keys that +were being held down when the key was released. + +
+ +
+ +
+
Scheme Variable: text-input-hook
+

A hook that is run when printable text is typed on the keyboard. This +hook is run with a single argument, text, a string containing +the text that was entered. +

+ +
+
Scheme Variable: mouse-press-hook
+

A hook that is run when a mouse button is pressed. This hook is run +with four arguments: +

+
    +
  1. button: The symbolic name of the button that was pressed, such +as left, middle, or right. + +
  2. clicks: The number of times the button has been clicked in a row. + +
  3. x: The x coordinate of the mouse cursor. + +
  4. y: The y coordinate of the mouse cursor. + +
+ +
+ +
+
Scheme Variable: mouse-release-hook
+

A hook that is run when a mouse button is released. This hook is run +with three arguments: +

+
    +
  1. button: The symbolic name of the button that was released. + +
  2. x: The x coordinate of the mouse cursor. + +
  3. y: The y coordinate of the mouse cursor. + +
+ +
+ +
+
Scheme Variable: mouse-move-hook
+

A hook that is run when the mouse is moved. This hook is run with +five arguments: +

+
    +
  1. x: The x coordinate of the mouse cursor. + +
  2. y: The y coordinate of the mouse cursor. + +
  3. dx: The amount the mouse has moved along the x axis since the +last mouse move event. + +
  4. dy: The amount the mouse has moved along the y axis since the +last mouse move event. + +
  5. buttons: A list of the buttons that were pressed down when the +mouse was moved. + +
+ +
+ +
+
Scheme Variable: controller-add-hook
+

A hook that is run when a game controller is connected. This hook is +run with a single argument, controller, the controller that was +connected. +

+ +
+
Scheme Variable: controller-remove-hook
+

A hook that is run when a game controller is disconnected. This hook +is run with a single argument, controller, the controller that +was disconnected. +

+ +
+
Scheme Variable: controller-press-hook
+

A hook that is run when a button on a game controller is pressed. +This hook is run with two arguments: +

+
    +
  1. controller: The controller that triggered the event. + +
  2. button: The symbolic name of the button that was pressed. +Possible buttons are: + +
      +
    • a +
    • b +
    • x +
    • y +
    • back +
    • guide +
    • start +
    • left-stick +
    • right-stick +
    • left-shoulder +
    • right-shoulder +
    • dpad-up +
    • dpad-down +
    • dpad-left +
    • dpad-right + +
    + +
+ +
+ +
+
Scheme Variable: controller-release-hook
+

A hook that is run when a button on a game controller is released. +

+

This hook is run with two arguments: +

+
    +
  1. controller: The controller that triggered the event. + +
  2. button: The symbolic name of the button that was released. + +
+ +
+ +
+
Scheme Variable: controller-move-hook
+

A hook that is run when an analog stick or trigger on a game +controller is moved. This hook is run with three arguments +

+
    +
  1. controller: The controller that triggered the event. + +
  2. axis: The symbolic name of the axis that was moved. Possible +values are: + +
      +
    • left-x +
    • left-y +
    • right-x +
    • right-y +
    • trigger-left +
    • trigger-right +
    + +
+ +
+ +
+
+

+Next: , Up: API Reference   [Contents][Index]

+
+ + + + + -- cgit v1.2.3