~ubuntu-branches/ubuntu/vivid/inform/vivid

<TR><TD Valign="top"><A HREF="contents.html">Contents</A> <A HREF="sectionA6.html">Back</A> <A HREF="sectionA8.html">Forward</A><TD bgcolor="#F5DEB3"><BLOCKQUOTE><H3>A7. Library-defined objects and routines</H3></BLOCKQUOTE><TR><TD><TD>

The library defines the following

special objects:

<DT><TT>compass</TT><DD>

To contain the directions. A direction object provides a

<TT>door_dir</TT> property, and should have the <TT>direction</TT> attribute. A compass

direction with <TT>enterable</TT>, if there is one (which there usually isn't),

will have an <TT>Enter</TT> action converted to <TT>Go</TT>.

Both the object signifying the abstract concept of 'northness', and the

'north wall' of the current room. (Thus, if a player types "examine the

north wall'' then the action <TT>Examine n_obj</TT> will be generated.) Its

<TT>door_dir</TT> property holds the direction property it corresponds to (<TT>n_to</TT>).

The other such objects are <TT>s_obj</TT>, <TT>e_obj</TT>, <TT>w_obj</TT>, <TT>ne_obj</TT>, <TT>nw_obj</TT>,

<TT>se_obj</TT>, <TT>sw_obj</TT>, <TT>u_obj</TT>, <TT>d_obj</TT>, <TT>in_obj</TT> and <TT>out_obj</TT>.

Note that the parser understands "ceiling'' to refer to <TT>u_obj</TT> and "floor'' to refer to

<TT>d_obj</TT>. (<TT>in_obj</TT> and <TT>out_obj</TT> differ slightly, because "in'' and

"out'' are verbs with other effects in some cases; these objects should not

be removed from the <TT>compass</TT>.)

<DT><TT>thedark</TT><DD>

A pseudo-room representing 'being in darkness'. <TT>location</TT>

is then set to this room, but the player object is not moved to it. Its

<TT>description</TT> can be changed to whatever "It is dark here'' message is

desired.

<DT><TT>selfobj</TT><DD>

The default player-object. Code should never refer directly

to <TT>selfobj</TT>, but only to <TT>player</TT>, a variable whose value is usually indeed

<TT>selfobj</TT> but which might become <TT>green_frog</TT> if the player is transformed

into one.

<DT><TT>InformLibrary</TT><DD>

Represents the library. You never need to use

it, but it might sometimes be the value of <TT>sender</TT> when a message is received.

<DT><TT>InformParser</TT><DD>

Represents the parser.

The following routines are defined in the library and available for public

use:

<DT><TT>Achieved(task)</TT><DD>

Indicate the <TT>task</TT> is achieved (which only

awards score the first time).

<DT><TT>AddToScope(obj)</TT><DD>

Used in an <TT>add_to_scope</TT> routine of an object to add another object

into scope whenever the first is in scope.

<DT><TT>AllowPushDir()</TT><DD>

Signal that an attempt to push an object from

one place to another should be allowed.

<DT><TT>CDefArt(obj)</TT><DD>

Print the capitalised definite article and

short name of <TT>obj</TT>. Equivalent to <TT>print (The) obj;</TT>.

<DT><TT>ChangeDefault(p,v)</TT><DD>

Changes the default value of property <TT>p</TT>. (But this won't

do anything useful to <TT>name</TT>.)

<DT><TT>ChangePlayer(obj,flag)</TT><DD>

Cause the player at the keyboard to

play as the given object, which must have a <TT>number</TT> property supplied. If

the <TT>flag</TT> is set to 1, then subsequently print messages like "(as Ford

Prefect)'' in room description headers. This routine, however, prints nothing

itself.

<DT><TT>DefArt(obj)</TT><DD>

100

101

Print the definite article and short name of

102

<TT>obj</TT>. Equivalent to <TT>print (the) obj;</TT>.

103

104

105

<DT><TT>DoMenu(text,R1,R2)</TT><DD>

106

107

Produce a menu, using the two routines given.

108

109

110

<DT><TT>EnglishNumber(x)</TT><DD>

111

112

Prints out <TT>x</TT> in English (e.g., "two hundred and seventy-seven").

113

114

115

<DT><TT>HasLightSource(obj)</TT><DD>

116

117

Returns true if <TT>obj</TT> 'has light'.

118

119

120

<DT><TT>InDefArt(obj)</TT><DD>

121

122

Print the indefinite article and short name

123

of <TT>obj</TT>. Equivalent to <TT>print (a) obj;</TT>.

124

125

126

<DT><TT>Locale(obj,tx1,tx2)</TT><DD>

127

128

Prints out the paragraphs of room description which would appear

129

if <TT>obj</TT> were the room: i.e., prints out descriptions of objects

130

in <TT>obj</TT> according to the usual rules. After describing the

131

objects which have their own paragraphs, a list is given of

132

the remaining ones. The string <TT>tx1</TT> is printed if there were

133

no previous paragraphs, and the string <TT>tx2</TT> otherwise.

134

(For instance, you might want "On the ledge you can see''

135

and "On the ledge you can also see''.) After the list, nothing

136

else is printed (not even a full stop) and the return value is

137

the number of objects in the list (possibly zero).

138

139

140

<DT><TT>LoopOverScope(R,actor)</TT><DD>

141

142

Calls routine <TT>R(obj)</TT> for each object <TT>obj</TT> in scope. <TT>actor</TT>

143

is optional: if it's given, then scope is calculated for the

144

given actor, not the player.

145

146

147

<DT><TT>NextWord()</TT><DD>

148

149

Returns the next dictionary word in the player's

150

input, moving the word number <TT>wn</TT> on by one. Returns 0

151

if the word is not in the dictionary or if the word stream has

152

run out.

153

154

155

<DT><TT>NextWordStopped()</TT><DD>

156

157

As <TT>NextWord</TT>, but returning -1 when the word stream has run out.

158

159

160

<DT><TT>NounDomain(o1,o2,type)</TT><DD>

161

162

This routine is one of the keystones of the parser: the objects

163

given are the domains to search through when parsing (almost

164

always the location and the actor) and the <TT>type</TT> indicates a

165

token. The only tokens safely usable are: 0: <TABLE Border><TR><TD><TT>noun</TT></TABLE>,

166

1: <TABLE Border><TR><TD><TT>held</TT></TABLE> and 6: <TABLE Border><TR><TD><TT>creature</TT></TABLE>. The routine parses

167

the best single object name it can from the current position

168

of <TT>wn</TT>. It returns 0 (no match), an object number or

169

the constant <TT>REPARSE_CODE</TT> (to indicate that it had to ask

170

a clarifying question: this reconstructed the input drastically

171

and the parser must begin all over again). <TT>NounDomain</TT> should

172

only be used by general parsing routines and these should

173

always return <TT>REPARSE_CODE</TT> if it does. Note that all of the

174

usual scope and name-parsing rules apply to the search performed

175

by <TT>NounDomain</TT>.

176

177

178

<DT><TT>ObjectIsUntouchable</TT><DD>

179

180

Determines whether any solid barrier (that is, any <TT>container</TT> that

181

is not <TT>open</TT>) lies between the player and <TT>obj</TT>. If <TT>flag</TT> is set,

182

this routine never prints anything; otherwise it prints a message

183

like "You can't, because ... is in the way.'' if any barrier is

184

found. Returns <TT>true</TT> if a barrier is found, <TT>false</TT> if not.

185

186

187

<DT><TT>OffersLight(obj)</TT><DD>

188

189

Returns true if <TT>obj</TT> 'offers light'.

190

191

192

<DT><TT>PlaceInScope(obj)</TT><DD>

193

194

Puts <TT>obj</TT> into scope for the parser.

195

196

197

<DT><TT>PlayerTo(place,flag)</TT><DD>

198

199

Move the player to <TT>place</TT>. Unless

200

<TT>flag</TT> is given and is 1, describe the player's surroundings.

201

202

203

<DT><TT>PrintShortName(obj)</TT><DD>

204

205

Print the short name of <TT>obj</TT>.

206

(This is protected against <TT>obj</TT> having a meaningless value.)

207

Equivalent to <TT>print (name) obj;</TT>.

208

209

210

<DT><TT>ScopeWithin(obj)</TT><DD>

211

212

Puts the contents of <TT>obj</TT> into scope,

213

recursing downward according to the usual scope rules.

214

215

216

<DT><TT>SetTime(time,rate)</TT><DD>

217

218

Set the game clock (a 24-hour clock) to the

219

given <TT>time</TT> (in seconds since the start of the day), to run at the given <TT>rate</TT> r:

220

r=0

221

means it does not run, if

222

r>0

223

then r seconds pass every turn,

224

225

r<0

226

then

227

-r

228

turns pass every second.

229

230

231

<DT><TT>StartDaemon(obj)</TT><DD>

232

233

Makes the daemon of <TT>obj</TT> active, so

234

that its <TT>daemon</TT> routine will be called every turn.

235

236

237

<DT><TT>StartTimer(obj,time)</TT><DD>

238

239

Starts the timer of <TT>obj</TT>, set

240

to go off in <TT>time</TT> turns, at which time its <TT>time_out</TT> routine will be called

241

(it must provide a <TT>time_left</TT> property).

242

243

244

<DT><TT>StopDaemon(obj)</TT><DD>

245

246

Makes the daemon of <TT>obj</TT> inactive, so

247

that its <TT>daemon</TT> routine is no longer called.

248

249

250

<DT><TT>StopTimer(obj)</TT><DD>

251

252

Stops the timer of <TT>obj</TT>, so that

253

it won't go off after all.

254

255

256

<DT><TT>TestScope(obj,actor)</TT><DD>

257

258

Returns true if <TT>obj</TT> is in scope; otherwise false. <TT>actor</TT>

259

is optional: if it's given, then scope is calculated for the

260

given actor, not the player.

261

262

263

<DT><TT>TryNumber(wordnum)</TT><DD>

264

265

Tries to parse the word at <TT>wordnum</TT> as a

266

number (recognising decimal numbers and English ones from "one'' to

267

"twenty''), returning

268

-1000

269

if it fails altogether, or the number.

270

Values exceeding 10000 are rounded down to 10000.

271

272

273

<DT><TT>UnsignedCompare(a,b)</TT><DD>

274

275

Returns 1 if a greater than b, 0 if a equals b and -1 if a less than b,

276

regarding a and b as unsigned

277

numbers between 0 and 65535 (or <TT>$ffff</TT>). (The usual <TT>></TT> condition performs

278

a signed comparison.)

279

280

281

<DT><TT>WordAddress(n)</TT><DD>

282

283

Returns the byte array containing the raw text of the n-th

284

word in the word stream.

285

286

287

<DT><TT>WordLength(n)</TT><DD>

288

289

Returns the length of the raw text of the n-th

290

word in the word stream.

291

292

293

<DT><TT>WriteListFrom(obj,s)</TT><DD>

294

295

Write a list of <TT>obj</TT> and its

296

siblings, with the style being <TT>s</TT> (a bitmap of options).

297

298

299

<DT><TT>YesOrNo()</TT><DD>

300

301

Assuming that a question has already been printed,

302

wait for the player to type "yes'' or "no'', returning true or false

303

accordingly.

304

305

306

<DT><TT>ZRegion(value)</TT><DD>

307

308

Works out the type of <TT>value</TT>, if possible. Returns 1 if it's a valid

309

object number, 2 if a routine address, 3 if a string address and 0

310

otherwise.

311

</TABLE>

312

<HR><A HREF="contents.html">Contents</A> / <A HREF="sectionA6.html">Back</A> / <A HREF="sectionA8.html">Forward</A>

313

<A HREF="chapter1.html">Chapter I</A> / <A HREF="chapter2.html">Chapter II</A> / <A HREF="chapter3.html">Chapter III</A> / <A HREF="chapter4.html">Chapter IV</A> / <A HREF="chapter5.html">Chapter V</A> / <A HREF="chapter6.html">Chapter VI</A> / <A HREF="chapterA.html">Appendix</A><HR>Mechanically translated to HTML from third edition as revised 16 May 1997. Copyright © Graham Nelson 1993, 1994, 1995, 1996, 1997: all rights reserved.</BODY></HTML>

Older »