This distribution should include these instructions, Aqua.h, Sploosh.inf (a sample game using Aqua), and Sploosh.z5 (that sample game compiled in playable form), as well as a hacked version of parserm.h also by Emily.

This library may be freely included in your Inform game files. Credit is appreciated, but not demanded.

• Basic setup
• Making a new liquid object
• Floating objects
• Absorbents
• Containers
• Full list of features

• Include "Aqua" after Parser but before Verblib
• Use the lightly-hacked version of parserm.h included with this package; this allows for intelligent liquid disambiguation. (If you don't like that idea or have done your own parser hacking, you can find the changes Emily made to the parser by searching for HACK (all caps) and extracting the relevant changes for yourself.)
• Call Water_Init(); in the Initialise routine
• After including Grammar, add this line:

  Extend 'squeeze' * noun 'into'/'in'/'on'/'onto'/'over' noun -> SqueezeInto;

• If you make all your locations of a class "Room", spills on the floor and puddles will also be correctly handled.

• You make a new liquid by declaring an object of class Liquid. So for instance, the olive oil in Savoir-Faire looks like this (slightly modified to decrease spoilage):

  Liquid oliveoil "olive oil", with spec_name "olive oil", name "olive" "oil", description [; "Clear yellow and viscous."; ], has edible;

• Special properties a liquid can have:
  • spec_name. Use this instead of short_name because short_name is already in use. All liquids should have a spec_name property.
  • number. Number indicates how much of the liquid there is.
    • Less than 40 is described as "not much";
    • less than 100 is "some";
    • 100 to 500 is "a great deal".
    • If the player drinks, he will drink between 10 and 20 units per sip.
  • mixtaste. Mixtaste is optional; it is used to tell what the liquid will taste like when combined with other liquids.
    • Mixtaste is called if this liquid is the dominant liquid in a mixture.
    • mixtaste takes as an argument the next-most-prevalent liquid in the mix.
    • So for instance, the wine in Savoir-Faire has the following mixtaste routine (slightly modified to decrease spoilage):

      mixtaste [ other; switch(other) { oliveoil: "More of a salad dressing than a beverage."; water: "The wine is dominant over the water, but the water is still definitely there. Stuff for children. You swallow resentfully."; mint_tea: "After a moment's concentration, you manage to swallow. The effect is queerly medicinal."; } ];

• If you want some of a liquid to move to a new container, call liquid.deploy([new container], [number of units to move]). This will take care of creating a new liquid object if necessary, mixing the liquids and dampening objects in the new container if necessary, etc.
• If you want to create some of a liquid in a new container (say you have a magic spell that copies all the liquid in one container into another container without removing any of the original liquid), you may invoke MakeLiquidCopy([original liquid to copy from], [number of units in the new liquid], [container into which the new liquid should be put]). So MakeLiquidCopy(milk, 5, blue_jar) would create 5 new units of milk in the blue jar.
• If you want a liquid in the game to go away, do not simply REMOVE LIQUID. Call liquid.evaporate(); This will remove the liquid from the object tree, but also reinitialize the object if it was dynamically generated.
• If you want to emulate a powder instead of a watery liquid, use the Liquid class as usual, but give your powder ~wet. It will not cause floaters to float, but will otherwise mix like a liquid; mixtures of powders will remain dry until a wet liquid is added to them. (Note that the subtlety of proportions is not observed at this point: you could be adding an eyedropper of water to a vat of flour, and the result would still be considered wet. You are welcome to fiddle with this if it is likely to be important in your game.)
  • For instance:

    Liquid flour "flour", with number 50, name "flour", spec_name "flour", article "a quantity of", description [; "Fine sifted flour."; ], has ~wet edible;

• Any object will float if it receives the attribute "floater". For instance, in the sample file is a rubber duck:

  Object rubber_duck "rubber duck" lab, with name "rubber" "duck" "yellow" "adorable", describe [; if (self has floating) "^Your beloved rubber duck floats to and fro."; "^Your beloved rubber duck lies discarded at your feet."; ], description [; "An adorable rubber duck that has somehow managed to avoid being plunged into a vat of acid. So far, anyway."; ], has floater;

• Any object will be absorbent if it inherits the class "absorbent". For instance, in the sample file is a sponge:

  Absorbent sponge "sponge", with name "sponge", size 1, after [; douse: give self general; rfalse; ], description [; print "A sea sponge, sized and rounded like an apple. It is currently "; if (self has wet) "sopping wet."; if (self has general) "slightly damp."; "bone dry."; ];

• By default, an absorbent item will absorb 50 units of liquid. To change this, you may give it the property absorb followed by a number. Thus a sponge with absorb 3 would not be particularly useful. (Maybe it is a very small sponge.)
• Warning: due to the way absorbents keep track of their liquids, making an absorbent container/supporter will cause problems. One can presumably hack around this problem, but so far at least I have not had a dire need for absorbent containers and supporters.

• Any container object in the game will be allowed to contain liquids, in the ordinary course of things.
  • If you wish to make your own set of rules overriding this (perhaps you have a lot of paper envelopes you don't want the player to be allowed to fill with liquids), you may use the entry point BadContainer. Define the BadContainer routine before including Aqua. It should take one argument, the container to be examined, and should return false if the container is okay; otherwise it should print a denial message. For instance:

    [ BadContainer x; if (x ofclass cloth) { if (keep_silent) rtrue; "", (The) x, " is too porous."; } rfalse; ];

• You may also wish to give items in your game a size property. If you do so, the game will use this information to compute the capacities of containers and whether or not they can contain more than they currently do. (Note: this will not interfere with putting solid objects into containers otherwise. It will only affect pouring liquids and whether the game believes there is room for more such liquids.)
  • If you wish to use sizes, but to assign an item in your game a greater capacity than it would otherwise have, you may use the leak_cap property. For instance:

    Object InfiniteDitch "very deep ditch" Lab, with initial [; "A very deep ditch runs along one side of the room."; ], name "very" "deep" "ditch", leak_cap [; ! Whatever its apparent size, it will keep on accepting liquids ! virtually forever. return 10000; ], has container open ~openable;

• If you wish a container in your game to slowly lose its contents over a long period, you may give it a water_leak property. Water_leak is called once when the the container is filled and then each turn that the container continues to contain liquid (including the turn on which it has been filled). For instance, a container from which liquids gradually evaporate might look like this:

  Object pot "pot", with name "pot", leak_cap [; return 200; ], water_leak [ liq flag par; if (flag==0) rfalse; liq.number = liq.number-5; if (TestScope(self)) { new_line; if (liq.number) print "Some of ", (the) liq; else print (The) liq; print " boils off.^"; } if (liq.number < 1) liq.evaporate(); ], has open container ~openable;

  • You could also use water_leak to make a container that leaks every turn. Doing this right is more complex than you might think, unfortunately. However, this particular use of water_leak seems likely to come up often enough that a class, Leaky, has been provided. So you could also just do

    Leaky leaky_container "leaky container", with name "leaky" "container", leak_cap [; return 200; ], drip 10, has open ~openable;

  • The drip property of a Leaky item indicates how much will flow out each turn. The default quantity is 5 units.
  • The describe_leak property of a Leaky item simply prints an appropriate description of the leakage. You may thus alter that description without having to replace the water_leak property entirely.
• Water_leak is called with two arguments: the liquid that it contains, and a flag. Flag is set to 0 if the container has just been filled (ie, we would be printing something as part of the filling description) and 1 if the container is being called on subsequent occasions.
• Note that water_leak need not print a message every turn, if you find this annoying; you might, for instance, have it print randomly only every three turns or so.

Features:

• A liquid object possesses the properties of
  • quantity (how much exists)
  • source (what liquid it originally came from)
• A liquid object can possess the attributes
  • wet (non-wet liquids are powders; see below)
  • edible (only edible liquids may be drunk)
• Liquids can be contained in any non-porous container
  • While the liquid is in inventory, the container's contents will be described in such a way as to indicate about how full the container is
  • If there is difficulty disambiguating between two liquids of the same name, the game will ask the player (and understand the answer to), "do you mean the water in the cup or the water in the jar?"
    • To avoid annoyance, the water is not otherwise routinely referred to as "the water in the jar"
  • Open containers of liquid cannot be put into the game's sack object
  • If an open container is thrown or hit, it will spill the liquid
  • If a container is broken, it will spill the liquid
• Liquids are divisible; different amounts can be held in a container
  • Drinking a liquid will remove a quantity that is variable within a given range. This is to prevent the player solving any measurement puzzles by measuring in 'sips.'
    • Different-sized sips are described by the randomizer as small sips, sips, or long drafts, so that the player at least has a sense of roughly how much has been drunk
  • Pouring a liquid from one container to another checks the capacity of the new container. If it is less (counting all the solid and liquid objects already therein) than the quantity of liquid demands, the liquid object will be divided.
  • A container may be defined with a leakiness routine. If it is defined, the liquid will call this routine each turn to determine whether it should be doing anything
    • The leakiness routine can be used to simulate the effects of gradual removal of the water through such effects as dripping, evaporation, or flow into another segment of, eg, a pipe.
• Liquids can be mixed
  • Mixtures of liquids 'remember' what their contents are and what the percentage of their component liquids are
    • Tastes of liquid mixtures default to a description that mentions the two most prevalent liquids in the mix.
      • It is possible to override this feature with a routine that will print an individual description of the taste of two or more specific liquids.
  • Combining two liquids of the same source makes them back into one and does not use the terminology of mixture
  • A mixture of liquids is flagged 'edible' only as long as all its components are edible
• Some materials are able to float
  • Pouring a liquid into a container containing a 'floater' will automatically cause the object to float to the top of the container
• Some materials are absorbent
  • Placing an object of class absorbent in a liquid or pouring a liquid over the absorbent object will cause it to become wet
  • Absorbent objects remember what kind of liquid they contain
  • Squeezing an absorbent object will dry it
    • Squeezing an absorbent object into a container will move a quantity of the appropriate liquid into that container
    • Squeezing a wet absorbent object over another object, or wiping another object with a wet absorbent object, will cause the other object to become wet
• Powders are modelled as dry liquids
  • Floater objects in powders do not float to the surface
  • Absorbent objects do not absorb powders
  • Mixtures become wet as soon as any 'wet' liquid is added to them; otherwise they are dry mixtures
• Locations are construed to be a single container
  • Pouring liquids on the ground will cause them to mix into a single puddle
  • The player is prevented from drinking liquids that are on the ground
  • Puddles in a location do not cause other objects there to float