Documentation examples in general; simulationOf and interactionOf in particular

[Gregory Weber]

In the documentation of Prelude in codeworld-base-0.1.0.0, as shown by the "Help" button on http://www.codeworld.info/# , the description of many functions needs some explanation and examples, in addition to the automatically generated type signatures.  For example, in the "Text" section, stripPrefix and stripSuffix have this, but most other functions do not.

At the moment, I am most concerned with understanding the types of some of the "Entry Points" functions:

The introductory section gives these examples:

main = simulationOf(start, step, draw)
main = interactionOf(start, step, event, draw)

saying that start is the initial state of the world, step describes how the world changes over time, and event describes how the state changes in response to a (user input) event.

However, the types shown at the bottom of the page

simulationOf :: ([Number] -> a, (a, Number) -> a, a -> Picture) -> Program

interactionOf :: ([Number] -> a, (a, Number) -> a, (a, Event) -> a, a -> Picture) -> Program

imply that the type of start is [Number] -> a, a function that takes a list of Numbers and returns the world state (type a).  I'm wondering what the role of the list of numbers is.  From the "Bounce" example, I get the idea that it is an infinite stream of random numbers, probably sampled from uniform [0, 1), from which the start function takes as many as needed (in this case, 4) to initialize the world.  Is this correct?

If so, and since the types of step and event lack the list of random numbers, the simulation or interaction would proceed deterministically after the initialization.  But in many kinds of simulation and interactions (games), it would be desirable to have random behaviors after the start of the simulation.

[Chris Smith]

Gregory Weber <spotte...@gmail.com> wrote:
> In the documentation of Prelude in codeworld-base-0.1.0.0, as shown by the
> "Help" button on http://www.codeworld.info/# , the description of many
> functions needs some explanation and examples, in addition to the
> automatically generated type signatures. For example, in the "Text"
> section, stripPrefix and stripSuffix have this, but most other functions do
> not.

Indeed, this is something I'm actively working on. I hope that the
situation will be much better after this weekend.

> I'm wondering what the
> role of the list of numbers is. From the "Bounce" example, I get the idea
> that it is an infinite stream of random numbers, probably sampled from
> uniform [0, 1), from which the start function takes as many as needed (in
> this case, 4) to initialize the world. Is this correct?

This is exactly correct. It is a list of random numbers uniformly
distributed over [0,1).

> If so, and since the types of step and event lack the list of random
> numbers, the simulation or interaction would proceed deterministically after
> the initialization. But in many kinds of simulation and interactions
> (games), it would be desirable to have random behaviors after the start of
> the simulation.

Indeed. In such cases, the world type (the 'a' in the type
signatures) should save the list of remaining random numbers. An
example (a little longer than you might hope for, but it's what I had
sitting around) is at http://codeworld.info/#PS8xB7AEamlaOXOoR6YwdzA==
; in particular, the Env type saves the list of random numbers, and
the function addEnemies samples from it to determine whether a new
enemy should appear and if so, which direction it should approach
from. The resulting world state then stores only the remaining random
numbers, so that a different decision will be made next time.

Hope that helps!

[Gregory Weber]

Ah yes!  The world type should save the random numbers -- that makes perfect sense.  Thanks for clarifying!