diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,4 @@ +1.2.2.0 +======= + +* Added CHANGELOG.md and `extra-source-files` to cabal file. diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,27 @@ +gore-and-ash +============ + +Core package of game engine called Gore&Ash. The engine has following features: + +- based on arrowised FRP ([netwire](https://wiki.haskell.org/Netwire)) + +- provides high-modularity and reusability. Actually the core can only compose modules that extends engine capabilities. + +- actor based style of programming, see [gore-and-ash-actor](https://github.com/Teaspot-Studio/gore-and-ash-actor) module. + +- network API over UDP with user controlled reliability, see [gore-and-ash-network](https://github.com/Teaspot-Studio/gore-and-ash-network) module. + +- synchronization EDSL that greately simplifies complexity of client-server programming, see [gore-and-ash-sync](https://github.com/Teaspot-Studio/gore-and-ash-sync) module. + +- input module via SDL2 library, see [gore-and-ash-sdl](https://github.com/Teaspot-Studio/gore-and-ash-sdl) module. + +For complete proof-of-concept, see [gore-and-ash-demo](https://github.com/Teaspot-Studio/gore-and-ash-demo) repo that contains implementation of simple game. + +Making your own module +====================== + +You can generate backbone of core module with `stack`: + +``` +stack new gore-and-ash-testtemp ./gore-and-ash-module.hsfiles -p module-name:TestTemp -p module-name-lower:testtemp --solver +``` diff --git a/README_netwire.md b/README_netwire.md new file mode 100644 --- /dev/null +++ b/README_netwire.md @@ -0,0 +1,437 @@ +Netwire +======= + +Netwire is a functional reactive programming (FRP) library with signal +inhibition. It implements three related concepts, *wires*, *intervals* +and *events*, the most important of which is the *wire*. To work with +wires we will need a few imports: + + import FRP.Netwire + import Prelude hiding ((.), id) + +The `FRP.Netwire` module exports the basic types and helper functions. +It also has some convenience reexports you will pretty much always need +when working with wires, including `Control.Category`. This is why we +need the explicit `Prelude` import. + +In general wires are generalized automaton arrows, so you can express +many design patterns using them. The `FRP.Netwire` module provides a +proper FRP framework based on them, which strictly respects continuous +time and discrete event semantics. When developing a framework based on +Netwire, e.g. a GUI library or a game engine, you may want to import +`Control.Wire` instead. + + +Introduction +------------ + +The following type is central to the entire library: + + data Wire s e m a b + +Don't worry about the large number of type arguments. They all have +very simple meanings, which will be explained below. + +A value of this type is called a *wire* and represents a *reactive* +value of type $b$, that is a value that may change over time. It may +depend on a reactive value of type $a$. In a sense a wire is a function +from a reactive value of type $a$ to a reactive value of type $b$, so +whenever you see something of type `Wire s e m a b` your mind should +draw an arrow from $a$ to $b$. In FRP terminology a reactive value is +called a *behavior*. + +A constant reactive value can be constructed using `pure`: + + pure 15 + +This wire is the reactive value 15. It does not depend on other +reactive values and does not change over time. This suggests that there +is an applicative interface to wires, which is indeed the case: + + liftA2 (+) (pure 15) (pure 17) + +This reactive value is the sum of two reactive values, each of which is +just a constant, 15 and 17 respectively. So this is the constant +reactive value 32. Let's spell out its type: + + myWire :: (Monad m, Num b) => Wire s e m a b + myWire = liftA2 (+) (pure 15) (pure 17) + +This indicates that $m$ is some kind of underlying monad. As an +application developer you don't have to concern yourself much about it. +Framework developers can use it to allow wires to access environment +values through a reader monad or to produce something (like a GUI) +through a writer monad. + +The wires we have seen so far are rather boring. Let's look at a more +interesting one: + + time :: (HasTime t s) => Wire s e m a t + +This wire represents the current local time, which starts at zero when +execution begins. It does not make any assumptions about the time type +other than that it is a numeric type with a `Real` instance. This is +enforced implicitly by the `HasTime` constraint. + +The type of this wire gives some insight into the $s$ parameter. Wires +are generally pure and do not have access to the system clock or other +run-time information. The timing information has to come from outside +and is passed to the wire through a value of type $s$, called the *state +delta*. We will learn more about this in the next section about +executing wires. + +Since there is an applicative interface you can also apply `fmap` to a +wire to apply a function to its value: + + fmap (2*) time + +This reactive value is a clock that is twice as fast as the regular +local time clock. If you use system time as your clock, then the time +type $t$ will most likely be `NominalDiffTime` from `Data.Time.Clock`. +However, you will usually want to have time of type `Double` or some +other floating point type. There is a predefined wire for this: + + timeF :: (Fractional b, HasTime t s, Monad m) => Wire s e m a b + timeF = fmap realToFrac time + +If you think of reactive values as graphs with the horizontal axis +representing time, then the `time` wire is just a straight diagonal line +and constant wires (constructed by `pure`) are just horizontal lines. +You can use the applicative interface to perform arithmetic on them: + + liftA2 (\t c -> c - 2*t) time (pure 60) + +This gives you a countdown clock that starts at 60 and runs twice as +fast as the regular clock. So it after two seconds its value will be +56, decreasing by 2 each second. + + +Testing wires +------------- + +Enough theory, we wanna see some performance now! Let's write a simple +program to test a constant (`pure`) wire: + + import Control.Wire + import Prelude hiding ((.), id) + + wire :: (Monad m) => Wire s () m a Integer + wire = pure 15 + + main :: IO () + main = testWire (pure ()) wire + +This should just display the value 15. Abort the program by pressing +Ctrl-C. The `testWire` function is a convenience to examine wires. It +just executes the wire and continuously prints its value to stdout: + + testWire :: + (MonadIO m, Show b, Show e) + => Session m s + -> (forall a. Wire s e Identity a b) + -> m c + +The type signatures in Netwire are known to be scary. =) But like most +of the library the underlying meaning is actually very simple. +Conceptually the wire is run continuously step by step, at each step +increasing its local time slightly. This process is traditionally +called *stepping*. + +As an FRP developer you assume a continuous time model, so you don't +observe this stepping process from the point of view of your reactive +application, but it can be useful to know that wire execution is +actually a discrete process. + +The first argument of `testWire` needs some explanation. It is a recipe +for state deltas. In the above example we have just used `pure ()`, +meaning that we don't use anything stateful from the outside world, +particularly we don't use a clock. From the type signature it is also +clear that this sets `s = ()`. + +The second argument is the wire to run. The input type is quantified +meaning that it needs to be polymorphic in its input type. In other +words it means that the wire does not depend on any other reactive +value. The underlying monad is `Identity` with the obvious meaning that +this wire cannot have any monadic effects. + +The following application just displays the number of seconds passed +since program start (with some subsecond precision): + + wire :: (HasTime t s) => Wire s () m a t + wire = time + + main :: IO () + main = testWire clockSession_ wire + +Since this time the wire actually needs a clock we use `clockSession_` +as the second argument: + + clockSession_ :: + (Applicative m, MonadIO m) + => Session m (Timed NominalDiffTime ()) + +It will instantiate $s$ to be `Timed NominalDiffTime ()`. This type +indeed has a `HasTime` instance with $t$ being `NominalDiffTime`. In +simpler words it provides a clock to the wire. At first it may seem +weird to use `NominalDiffTime` instead of something like `UTCTime`, but +this is reasonable, because time is relative to the wire's start time. +Also later in the section about switching we will see that a wire does +not necessarily start when the program starts. + + +Constructing wires +------------------ + +Now that we know how to test wires we can start constructing more +complicated wires. First of all it is handy that there are many +convenience instances, including `Num`. Instead of `pure 15` we can +simply write `15`. Also instead of + + liftA2 (+) time (pure 17) + +we can simply write: + + time + 17 + +This clock starts at 17 instead of zero. Let's make it run twice as +fast: + + 2*time + 17 + +If you have trouble wrapping your head around such an expression it may +help to read `a*b + c` mathematically as $a(t) b(t) + c(t)$ and read +`time` as simply $t$. + +So far we have seen wires that ignore their input. The following wire +uses its input: + + integral 5 + +It literally integrates its input value with respect to time. Its +argument is the integration constant, i.e. the start value. To supply +an input simply compose it: + + integral 5 . 3 + +Remember that `3` really means `pure 3`, a constant wire. The integral +of the constant 3 is $3 t + c$ and here $c = 5$. Here is another +example: + + integral 5 . time + +Since `time` denotes $t$ the integral will be $\frac{1}{2} t^2 + c$, +again with $c = 5$. This may sound like a complicated, sophisticated +wire, but it's really not. Surprisingly there is no crazy algebra or +complicated numerical algorithm going on under the hood. Integrating +over time requires one addition and one division each frame. So there +is nothing wrong with using it extensively to animate a scene or to move +objects in a game. + +Sometimes categorical composition and the applicative interface can be +inconvenient, in which case you may choose to use the arrow interface. +The above integration can be expressed the following way: + + proc _ -> do + t <- time -< () + integral 5 -< t + +Since `time` ignores its input signal, we just give it a constant signal +with value `()`. We name time's value $t$ and pass it as the input +signal to `integral`. + + +Intervals +--------- + +Wires may choose to produce a signal only for a limited amount of time. +We refer to those wires as intervals. When a wire does not produce, +then it *inhibits*. Example: + + for 3 + +This wire acts like the identity wire in that it passes its input signal +through unchanged: + + for 3 . "yes" + +The signal of this wire will be "yes", but after three seconds it will +stop to act like the identity wire and will inhibit forever. + +When you use `testWire` inhibition will be displayed as "I:" followed by +a value, the *inhibition value*. This is what the $e$ parameter to +`Wire` is. It's called the *inhibition monoid*: + + for :: (HasTime t s, Monoid e) => t -> Wire s e m a a + +As you can see the input and output types are the same and fully +polymorphic, hinting at the identity-like behavior. All predefined +intervals inhibit with the `mempty` value. When the wire inhibits, you +don't get a signal of type $a$, but rather an inhibition value of type +$e$. Netwire does not interpret this value in any way and in most cases +you would simply use `e = ()`. + +Intervals give you a very elegant way to combine wires: + + for 3 . "yes" <|> "no" + +This wire produces "yes" for three seconds. Then the wire to the left +of `<|>` will stop producing, so `<|>` will use the wire to its right +instead. You can read the operator as a left-biased "or". The signal +of the wire `w1 <|> w2` will be the signal of the leftmost component +wire that actually produced a signal. There are a number of predefined +interval wires. The above signal can be written equivalently as: + + after 3 . "no" <|> "yes" + +The left wire will inhibit for the first three seconds, so during that +interval the right wire is chosen. After that, as suggested by its +name, the `after` wire starts acting like the identity wire, so the left +side takes precedence. Once the time period has passed the `after` wire +will produce forever, leaving the "yes" wire never to be reached again. +However, you can easily combine intervals: + + after 5 . for 6 . "Blip!" <|> "Look at me..." + +The left wire will produce after five seconds from the beginning for six +seconds from the beginning, so effectively it will produce for one +second. When you animate this wire, you will see the string "Look at +me..." for five seconds, then you will see "Blip!" for one second, then +finally it will go back to "Look at me..." and display that one forever. + + +Events +------ + +Events are things that happen at certain points in time. Examples +include button presses, network packets or even just reaching a certain +point in time. As such they can be thought of as lists of values +together with their occurrence times. Events are actually first class +signals of the `Event` type: + + data Event a + +For example the predefined `never` event is the event that never occurs: + + never :: Wire s e m a (Event b) + +As suggested by the type events contain a value. Netwire does not +export the constructors of the `Event` type by default. If you are a +framework developer you can import the `Control.Wire.Unsafe.Event` +module to implement your own events. A game engine may include events +for key presses or certain things happening in the scene. However, as +an application developer you should view this type as being opaque. +This is necessary in order to protect continuous time semantics. You +cannot access event values directly. + +There are a number of ways to respond to an event. The primary way to +do this in Netwire is to turn events into intervals. There are a number +of predefined wires for that purpose, for example `asSoonAs`: + + asSoonAs :: (Monoid e) => Wire s e m (Event a) a + +This wire takes an event signal as its input. Initially it inhibits, +but as soon as the event occurs for the first time, it produces the +event's last value forever. The `at` event will occur only once after +the given time period has passed: + + at :: (HasTime t s) => t -> Wire s e m a (Event a) + +Example: + + at 3 . "blubb" + +This event will occur after three seconds, and the event's value will be +"blubb". Using `asSoonAs` we can turn this into an interval: + + asSoonAs . at 3 . "blubb" + +This wire will inhibit for three seconds and then start producing. It +will produce the value "blubb" forever. That's the event's last value +after three seconds, and it will never change, because the event does +not occur ever again. Here is an example that may be more +representative of that property: + + asSoonAs . at 3 . time + +This wire inhibits for three seconds, then it produces the value 3 (or a +value close to it) forever. Notice that this is not a clock. It does +not produce the current time, but the `time` at the point in time when +the event occurred. + +To combine multiple events there are a number of options. In principle +you should think of event values to form a semigroup (of your choice), +because events can occur simultaneously. However, in many cases the +actual value of the event is not that interesting, so there is an easy +way to get a left- or right-biased combination: + + (at 2 <& at 3) . time + +This event occurs two times, namely once after two seconds and once +after three seconds. In each case the event value will be the +occurrence time. Here is an interesting case: + + at 2 . "blah" <& at 2 . "blubb" + +These events will occur simultaneously. The value will be "blah", +because `<&` means left-biased combination. There is also `&>` for +right-biased combination. If event values actually form a semigroup, +then you can just use monoidal composition: + + at 2 . "blah" <> at 2 . "blubb" + +Again these events occur at the same time, but this time the event value +will be "blahblubb". Note that you are using two Monoid instances and +one Semigroup instance here. If the signals of two wires form a monoid, +then wires themselves form a monoid: + + w1 <> w2 = liftA2 (<>) w1 w2 + +There are many predefined event-wires and many combinators for +manipulating events in the `Control.Wire.Event` module. A common events +is the `now` event: + + now :: Wire s e m a (Event a) + +This event occurs once at the beginning. + + +Switching +--------- + +We still lack a meaningful way to respond to events. This is where +*switching* comes in, sometimes also called *dynamic switching*. The +most important combinator for switching is `-->`: + + w1 --> w2 + +The idea is really straightforward: This wire acts like `w1` as long as +it produces. As soon as it stops producing it is discarded and `w2` +takes its place. Example: + + for 3 . "yes" --> "no" + +In this case the behavior will be the same as in the *intervals* +section, but with two major differences: Firstly when the first +interval ends, it is completely discarded and garbage-collected, never +to be seen again. Secondly and more importantly the point in time of +switching will be the beginning for the new wire. Example: + + for 3 . time --> time + +This wire will show a clock counting to three seconds, then it will +start over from zero. This is why we usually refer to time as *local +time*. + +Recursion is fully supported. Here is a fun example: + + netwireIsCool = + for 2 . "Once upon a time..." --> + for 3 . "... games were completely imperative..." --> + for 2 . "... but then..." --> + for 10 . ("Netwire 5! " <> anim) --> + netwireIsCool + + where + anim = + holdFor 0.5 . periodic 1 . "Hoo..." <|> + "...ray!" diff --git a/gore-and-ash.cabal b/gore-and-ash.cabal --- a/gore-and-ash.cabal +++ b/gore-and-ash.cabal @@ -1,5 +1,5 @@ name: gore-and-ash -version: 1.2.1.0 +version: 1.2.2.0 synopsis: Core of FRP game engine called Gore&Ash description: Please see README.md homepage: https://github.com/Teaspot-Studio/gore-and-ash @@ -13,6 +13,11 @@ category: Game build-type: Simple cabal-version: >=1.10 +extra-source-files: + README.md + README_netwire.md + CHANGELOG.md + stack.yaml library hs-source-dirs: src diff --git a/stack.yaml b/stack.yaml new file mode 100644 --- /dev/null +++ b/stack.yaml @@ -0,0 +1,32 @@ +# For more information, see: https://github.com/commercialhaskell/stack/blob/release/doc/yaml_configuration.md + +# Specifies the GHC version and set of packages available (e.g., lts-3.5, nightly-2015-09-21, ghc-7.10.2) +resolver: lts-7.9 + +# Local packages, usually specified by relative directory name +packages: +- '.' + +# Packages to be pulled from upstream that are not in the resolver (e.g., acme-missiles-0.3) +extra-deps: [] + +# Override default flag values for local packages and extra-deps +flags: {} + +# Extra package databases containing global packages +extra-package-dbs: [] + +# Control whether we use the GHC we find on the path +# system-ghc: true + +# Require a specific version of stack, using version ranges +# require-stack-version: -any # Default +# require-stack-version: >= 0.1.4.0 + +# Override the architecture used by stack, especially useful on Windows +# arch: i386 +# arch: x86_64 + +# Extra directories used by stack for building +# extra-include-dirs: [/path/to/dir] +# extra-lib-dirs: [/path/to/dir]