source: project/wiki/eggref/4/doodle @ 26070

Last change on this file since 26070 was 26070, checked in by Christian Kellermann, 10 years ago

doodle: narf markup sucks

File size: 9.5 KB
Line 
1[[tags: egg]]
2
3== doodle - A minimal game 'framework'.
4
5[[toc:]]
6
7=== Description
8
9A minimal game 'framework' inspired by [[http://love2d.org/|löve]].
10
11'''This is still a work in progress and subject to change!'''
12
13=== Code repository
14
15The source code for doodle is hosted on [[https://bitbucket.org/ckeen/doodle|bitbucket]].
16
17You can grab it with git:
18
19''git clone https://bitbucket.org/ckeen/doodle.git''
20
21=== Author
22
23[[/users/christian-kellermann|Christian Kellermann]]
24
25=== Requirements
26
27Requires the [[clojurian]], [[cairo]] and [[sdl]] extensions.
28
29=== General program flow of a doodle
30
31A program creates a window, called a 'doodle' here and registers for
32any of these three events: world-inits, world-ends and
33world-changes. world-inits is called upon the first iteration of the
34event loop, world-ends last and world-changes for every iteration.
35
36world-inits and world-ends are thunks, whereas world-changes has the
37following signature:
38
39<procedure>(world-changes (lambda (events dt escape-continuation) ...))</procedure>
40
41; event : holds the occured list of events of this loop iteration
42; dt : holds the time delta between the last and this iteration
43; escape-continuation : holds the continuation that will exit the loop
44
45Please see below for a detailed list of supported {{event}} symbols.
46
47{{dt}} is a flonum which can be used to adjust speed of animations for
48example.
49
50The game loop is started with the {{(run-event-loop)}} procedure.
51Usually the game loop will run as fast as it can unless the keyword
52parameter {{minimum-wait}} has been given which adds that minimum
53delay between iterations.
54
55=== API Documentation
56
57This egg is still under development; the API might change a bit in
58future versions.
59
60==== Event loop
61===== Procedures
62<procedure>(run-event-loop #!key (run-in-background #f) (minimum-wait 0))</procedure>
63
64Starts the event loop and runs {{world-inits}}. If
65{{run-in-background}} is #t a new thread is started. Within the event
66loop the procedure given with {{world-changes}} is called with the
67time delta of the last call and the events that occured. If
68{{minimum-wait}} is given and the delta is smaller than
69{{minimum-wait}} the thread will sleep for the remaining
70time. {{minimum-wait}} takes a srfi-18 time value.
71
72===== Parameters
73<parameter>(world-inits (lambda () ...))</parameter>
74
75A thunk that is called once when the event loop is started.
76
77<parameter>(world-ends (lambda () ...))</parameter>
78
79A thunk that is called once when the even loop is exited.
80
81<parameter>(world-changes (lambda (events dt exit-continuation) ...))</parameter>
82
83A procedure that gets called every iteration of the event loop. The
84{{events}} parameter holds the list of events, {{dt}} is the time
85difference in milliseconds between the last and current
86iteration. {{exit-continuation}} can be used to jump out of the
87event-loop.
88
89===== Events
90
91One event is a list containing information about the individual
92event. There are currently 3 types of handled events:
93
94; quit : The quit event has the following form {{(quit)}}.
95; key events : The first element of the list is the symbol {{key}} followed by either the symbol {{pressed}} or {{released}} followed by either the integer for the key code or the symbols {{up}}, {{down}}, {{left}} or {{right}} representing cursor keys.
96; mouse events: The first element of this list is the symbol {{mouse}}. There are three types of events: {{pressed}}, {{released}} and {{moved}}. The first two are followed by three values {{x}} {{y}} and {{button}}, representing the coordinates of the pointer and the button number being pressed or released. Mouse buttons are numbered 1-5, with 4,5 being rotations of the mouse wheel. {{moved}} events have the coordinates as their only arguments.
97; unknown : This will list all other events. The list contains the symbol {{unknown}} and the SDL event type. See the SDL egg documentation for hints on what this may be.
98
99==== Drawing
100===== Colors
101
102Colors in doodle are represented as simple lists representing RGBA
103values one number each. Currently there are two predefined colors:
104
105; solid-black : {{(0 0 0 1)}}
106; solid-white : {{(1 1 1 1)}}
107
108===== Procedures
109
110<procedure>(new-doodle #!key (width 680) (height 460) (title "Doodle") (background solid-black) (fullscreen #f))</procedure>
111
112Initialises the internal state and createas a window with the given
113dimensions and title. If background is a string it will be interpreted as a filename pointing to a PNG file which will be loaded as background.
114
115<procedure>(show!)</procedure>
116
117Causes a redraw of the window.
118
119<procedure>(clear-screen!)</procedure>
120
121Fills the screen with the {{current-background}} color.
122
123<procedure>(rectangle x y width height color)</procedure>
124
125Draws a rectangle at the given coordinates {{(x, y)}} with the
126dimensions {{width}} and {{height}}. The border is drawn in {{color}}.
127
128<procedure>(filled-rectangle x y width height color)</procedure>
129
130Draws a rectangle at the given coordinates {{(x, y)}} with the
131dimensions {{width}} and {{height}}. The border is drawn in
132{{color}}. The rectangle also is filled with {{color}}.
133
134<procedure>(circle x y diameter color)</procedure>
135
136Draws a circle at the point defined by {{(x,y)}} with the given
137{{diameter}} and {{color}}. The border is drawn in {{color}}.
138
139<procedure>(filled-circle x y diameter color)</procedure>
140
141Draws a circle at the point defined by {{(x,y)}} with the given
142{{diameter}} and {{color}}. The border is drawn in {{color}}. The
143circle is filled in {{color}} too.
144
145<procedure>(draw-line x1 y1 x2 y2 #!key (color solid-white) (style #:solid))</procedure>
146
147Draw a line between the two points {{(x1,y1)}} and {{(x2,y2)}} in the
148given style. Valid {{style}}s are either {{#:solid}} (the default) or
149{{#:dashed}} for dashed lines. The line is drawn in {{color}}.
150
151<procedure>(set-font! font size color)</procedure>
152
153Sets the font to {{font}}, given {{size}} and {{color}}. {{font}} is a
154string representing the font's name. Every X11 TTF font is applicable.
155
156<procedure>(text x y text #!key (align #:left))</procedure>
157
158Print the given text in one line starting on point
159{{(x,y)}}. Alignment can be changed with the {{align}}
160parameter. Supported alignment values are {{#:left}}, {{#:center}} and
161{{#:right}}.
162
163<procedure>(save-screenshot filename)</procedure>
164
165Saves the current screen content to a file called {{filename}} as a
166portable network graphics (PNG). It is up to the user to provide an
167appropriate extension to the filename.
168
169===== Exported values
170
171{{doodle-width}} and {{doodle-height}} hold the width and height of
172the window, that has been given on a call to {{(new-doodle)}}.
173
174===== Parameters
175
176<parameter>(font-color)</parameter>
177
178Holds the current font color.
179
180<parameter>(font-size)</parameter>
181
182Holds the current font-size.
183
184<parameter>(current-background)</parameter>
185
186Holds the current background color.
187
188==== Collision detection
189
190These are all still work in progress and might get moved away or in a
191separate module.
192
193*sprites*
194
195<procedure>add-sprite!</procedure>
196
197<procedure>check-for-collisions</procedure>
198
199<procedure>make-sprite</procedure>
200
201<procedure>remove-sprite!</procedure>
202
203<procedure>update-sprite!</procedure>
204
205==== Example
206
207The following example will show a little circle painting program. It
208requires the [[matchable]] egg.
209
210<enscript highlight="scheme">
211(use matchable doodle)
212
213(define *paint* #f)
214
215(define red '(1 0 0 0.3))
216
217(world-inits
218 (lambda ()
219   (clear-screen)
220   (set-font! "Vollkorn" 18 red)
221   (text (/ doodle-width 2)
222         (/ doodle-height 2) '("Welcome to doodle!"
223                               "Click the left mouse button to draw circles"
224                               "Press ESC to leave")
225         align: #:center)))
226
227(world-changes
228 (lambda (events dt exit)
229   (for-each
230    (lambda (e)
231      (match e
232       (('mouse 'pressed x y 1)
233        (set! *paint* #t)
234        (filled-circle x y 10 red))
235       (('mouse 'released x y 1)
236        (set! *paint* #f))
237       (('mouse 'moved x y)
238        (when *paint*
239          (filled-circle x y 10 red)))
240       (('key 'pressed #\esc)
241        (exit #t))
242       (else (void))))
243    events)))
244
245(new-doodle title: "Doodle paint" background: solid-white)
246(run-event-loop)
247
248</enscript>
249
250=== Changelog
251
252; 0.1 : Initial version
253; 0.2 : Fixed event handling, added mouse events, background images possible
254
255=== License
256
257  Copyright (c) 2012, Christian Kellermann
258  All rights reserved.
259
260  Redistribution and use in source and binary forms, with or without
261  modification, are permitted provided that the following conditions
262  are met:
263
264      Redistributions of source code must retain the above copyright
265      notice, this list of conditions and the following disclaimer.
266 
267      Redistributions in binary form must reproduce the above
268      copyright notice, this list of conditions and the following
269      disclaimer in the documentation and/or other materials provided
270      with the distribution.
271 
272  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
273  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
274  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
275  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
276  COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
277  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
278  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
279  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
280  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
281  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
282  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
283  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.