summaryrefslogtreecommitdiff
path: root/manuals/chickadee/Scripts.html
blob: c9939f5ef0dfd0b811abe9ebd33a6100ce515404 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 2017  David Thompson davet@gnu.org

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".

A copy of the license is also available from the Free Software
Foundation Web site at http://www.gnu.org/licenses/fdl.html.


The document was typeset with
http://www.texinfo.org/ (GNU Texinfo).
 -->
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Scripts (The Chickadee Game Toolkit)</title>

<meta name="description" content="Scripts (The Chickadee Game Toolkit)">
<meta name="keywords" content="Scripts (The Chickadee Game Toolkit)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index.html#Index" rel="index" title="Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Scripting.html#Scripting" rel="up" title="Scripting">
<link href="Tweening.html#Tweening" rel="next" title="Tweening">
<link href="Agendas.html#Agendas" rel="prev" title="Agendas">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
@media (min-width: 1140px) {
    body {
        margin-left: 14rem;
        margin-right: 4rem;
        max-width: 52rem;
    }
}

@media (min-width: 800px) and (max-width: 1140px) {
    body {
        margin-left: 6rem;
        margin-right: 4rem;
        max-width: 52rem;
    }
}

@media (max-width: 800px) {
    body {
        margin: 1rem;
    }
}

-->
</style>
<link rel="stylesheet" type="text/css" href="https://dthompson.us/css/dthompson.css">


</head>

<body lang="en">
<a name="Scripts"></a>
<div class="header">
<p>
Next: <a href="Tweening.html#Tweening" accesskey="n" rel="next">Tweening</a>, Previous: <a href="Agendas.html#Agendas" accesskey="p" rel="prev">Agendas</a>, Up: <a href="Scripting.html#Scripting" accesskey="u" rel="up">Scripting</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Scripts-1"></a>
<h4 class="subsection">2.4.2 Scripts</h4>

<p>Now that we can schedule tasks, let&rsquo;s take things to the next level.
It sure would be great if we could make procedures that described a
series of actions that happened over time, especially if we could do
so without contorting our code into a nest of callback procedures.
This is where scripts come in.  With scripts we can write code in a
linear way, in a manner that appears to be synchronous, but with the
ability to suspend periodically in order to let other scripts have a
turn and prevent blocking the game loop.  Building on top of the
scheduling that agendas provide, here is a script that models a child
trying to get their mother&rsquo;s attention:
</p>
<div class="example">
<pre class="example">(script
  (while #t
    (display &quot;mom!&quot;)
    (newline)
    (sleep 60))) ; where 60 = 1 second of real time
</pre></div>

<p>This code runs in an endless loop, but the <code>sleep</code> procedure
suspends the script and schedules it to be run later by the agenda.
So, after each iteration of the loop, control is returned back to the
game loop and the program is not stuck spinning in a loop that will
never exit.  Pretty neat, eh?
</p>
<p>Scripts can suspend to any capable handler, not just the agenda.
The <code>yield</code> procedure will suspend the current script and pass
its &ldquo;continuation&rdquo; to a handler procedure.  This handler procedure
could do anything.  Perhaps the handler stashes the continuation
somewhere where it will be resumed when the user presses a specific
key on the keyboard, or maybe it will be resumed when the player picks
up an item off of the dungeon floor; the sky is the limit.
</p>
<p>Sometimes it is necessary to abruptly terminate a script after it has
been started.  For example, when an enemy is defeated their AI routine
needs to be shut down.  When a script is spawned, a handle to that
script is returned that can be used to cancel it when desired.
</p>
<div class="example">
<pre class="example">(define script (script (while #t (display &quot;hey\n&quot;) (sleep 60))))
;; sometime later
(cancel-script script)
</pre></div>

<dl>
<dt><a name="index-spawn_002dscript"></a>Procedure: <strong>spawn-script</strong> <em><var>thunk</var></em></dt>
<dd><p>Apply <var>thunk</var> as a script and return a handle to it.
</p></dd></dl>

<dl>
<dt><a name="index-script"></a>Syntax: <strong>script</strong> <em><var>body</var> &hellip;</em></dt>
<dd><p>Evaluate <var>body</var> as a script and return a handle to it.
</p></dd></dl>

<dl>
<dt><a name="index-script_003f"></a>Procedure: <strong>script?</strong> <em><var>obj</var></em></dt>
<dd><p>Return <code>#t</code> if <var>obj</var> is a script handle.
</p></dd></dl>

<dl>
<dt><a name="index-script_002dcancelled_003f"></a>Procedure: <strong>script-cancelled?</strong> <em><var>obj</var></em></dt>
<dd><p>Return <code>#t</code> if <var>obj</var> has been cancelled.
</p></dd></dl>

<dl>
<dt><a name="index-script_002drunning_003f"></a>Procedure: <strong>script-running?</strong> <em><var>obj</var></em></dt>
<dd><p>Return <code>#t</code> if <var>obj</var> has not yet terminated or been
cancelled.
</p></dd></dl>

<dl>
<dt><a name="index-script_002dcomplete_003f"></a>Procedure: <strong>script-complete?</strong> <em><var>obj</var></em></dt>
<dd><p>Return <code>#t</code> if <var>obj</var> has terminated.
</p></dd></dl>

<dl>
<dt><a name="index-cancel_002dscript"></a>Procedure: <strong>cancel-script</strong> <em><var>co</var></em></dt>
<dd><p>Prevent further execution of the script <var>co</var>.
</p></dd></dl>

<dl>
<dt><a name="index-yield"></a>Procedure: <strong>yield</strong> <em><var>handler</var></em></dt>
<dd><p>Suspend the current script and pass its continuation to the
procedure <var>handler</var>.
</p></dd></dl>

<dl>
<dt><a name="index-sleep"></a>Procedure: <strong>sleep</strong> <em><var>duration</var></em></dt>
<dd><p>Wait <var>duration</var> before resuming the current script.
</p></dd></dl>

<dl>
<dt><a name="index-channel_002dget"></a>Procedure: <strong>channel-get</strong> <em><var>channel</var></em></dt>
<dd><p>Wait for a message from <var>channel</var>.
</p></dd></dl>

<dl>
<dt><a name="index-forever"></a>Syntax: <strong>forever</strong> <em><var>body</var> &hellip;</em></dt>
<dd><p>Evaluate <var>body</var> in an endless loop.
</p></dd></dl>

<hr>
<div class="header">
<p>
Next: <a href="Tweening.html#Tweening" accesskey="n" rel="next">Tweening</a>, Previous: <a href="Agendas.html#Agendas" accesskey="p" rel="prev">Agendas</a>, Up: <a href="Scripting.html#Scripting" accesskey="u" rel="up">Scripting</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>