Universe Library for OCaml

December 30, 2018

News

(2018 Dec 30) Updated to go with cairo 0.6 (thanks to Christophe Troestler).
(2017 Dec 20) A hostname (or IP address) and a port number are now passed as -ip and -port arguments, enabling to pass other command line arguments.
(2015 Feb 11) Conversion to Cairo.Image.data32 bitmap supported.

(2015 Jan 6) The library can now be installed via OPAM:

opam pin add universe https://github.com/kenichi-asai/Universe.git

(2015 Jan 1) Development moved to github.
(2014 Dec 24) Initial release.

1 What is the Universe Library for OCaml?

Racket has a wonderful universe teachpack for writing interactive games. For quick introduction, see a draft but wonderfully written textbook How to Design Worlds (for non-communicating games). For thorough introduction, see the 2nd edition of How to Design Programs.

The Universe Library for OCaml provides similar interface in OCaml, so that one can enjoy writing interactive games in OCaml.

2 Environments

We are developing the Universe Library using the following environments:

MacOSX 10.12
OCaml 4.02.0 and later
X11, gtk2, gnomecanvas, cairo2, lablgtk2
OCamlMakefile

3 Setting up

You need to have X11, gtk2, gnomecanvas, lablgtk2, and OCamlMakefile. We do as follows:

Install XQuartz, homebrew, and OPAM.

Install gtk2, gnomecanvas, and lablgtk.

brew install pkg-config
brew install cairo
brew install libgnomecanvas
opam install conf-gnomecanvas
opam install conf-cairo
opam install lablgtk
opam install cairo2
opam install cairo2-gtk

Install OCamlMakefile.
```
opam install ocaml-makefile
```

4 Installation

Via OPAM:

opam pin add universe https://github.com/kenichi-asai/Universe.git

Or you can do it manually:

Download the universe library from the github Universe repository.

The library has the following directory structure:

Universe/library/               : the Universe library
Universe/sample/ball-game1/     : sample non-communicating game
Universe/sample/ball-game2/     : sample communicating game

Create a link to OCamlMakefile in the Universe directory. If you installed OCamlMakefile via OPAM, type somethig like:

cd Universe
ln -s ~/.opam/4.02.0/lib/ocaml-makefile/OCamlMakefile .

Under the Universe/library directory, compile:
```
cd library
make
```

5 Module interface: English, Japanese

6 Sample games

Non-communicating ball game (source: ball-game1)

Click balls to make them all smallest.

Compile: make
Run: ./game

Communicating ball game (source: ball-game2)

Click the others' balls. When your balls all become smallest, you lose.

Compile: make
Launch a server: ./server
It will output a port number.
Launch clients as many as you want: ./client [-ip hostname] -port port-number

7 Create your own games

non-communicating games

Create a directory under sample.
```
cd sample
mkdir MyGame1
cd MyGame1
```
Copy Makefile from ball-game1.
```
cp ../ball-game1/Makefile .
```
Edit Makefile.
- OCAMLMAKEFILE should have the path to OCamlMakefile.
- If you installed the library via OPAM, you are done. Go to the next step and develop your game.
- If you manually installed the library to the place where ocamlfind does not know, instead of using:
```
PACKS = universe
```
  use the commented out lines:
```
PACKS = cairo2-gtk unix
INCDIRS = ../../library
LIBS = socket color image world universe
```
  where INCDIRS should have the path to the library directory.
Develop your game!
To compile: make
To run: ./game (as specified by RESULT in Makefile).

communicating games

Create a directory under sample.
```
cd sample
mkdir MyGame2
cd MyGame2
```

Copy Makefiles from ball-game2.

cp ../ball-game1/Makefile .
cp ../ball-game1/Makefile-client .
cp ../ball-game1/Makefile-server .

Edit Makefile-client and Makefile-server.
- OCAMLMAKEFILE should have the path to OCamlMakefile.
- If you installed the library via OPAM, you are done. Go to the next step and develop your game.
- If you manually installed the library to the place where ocamlfind does not know, instead of using:
```
PACKS = universe
```
  use the commented out lines:
```
PACKS = cairo2-gtk unix
INCDIRS = ../../library
LIBS = socket color image world universe
```
  where INCDIRS should have the path to the library directory.
Develop your game!
To compile: make
To run, first launch a server.
```
./server
```
It will output a port number. You can then launch as many clients as you want.
```
./client [-ip hostname] -port port-number
```
From the same machine as the server is running, you can omit the host name.

8 Create a toplevel with the Universe Library

If you installed the library via OPAM:

ocamlfind ocamlmktop -package universe,findlib -linkpkg -o universe.top

and you will obtain universe.top. To launch the toplevel, simply type:

./universe.top

and then in the toplevel:

#require "universe" ;;

Otherwise,

ocamlfind ocamlmktop -package cairo2-gtk,unix -linkpkg -I ../../library socket.cma color.cma image.cma world.cma -o universe.top

To launch the toplevel, you need to specify the library path:

./universe.top -I ../../library

(But currently, the argumet -I ../../library is interpreted by World module and does not work. Hmm.)

9 Known issues

Comments in ml files are in Japanese.
The @en and @ja tags in mli files are not working as intended. A feature request has been placed.

10 Papers

Uehara, C., and K. Asai ``Cross validation of the universe teachpack of Racket in OCaml,'' The 4th International Workshop on Trends in Functional Programming in Education (TFPIE 2015), 14 pages (June 2015). pdf.
上原千裕, 浅井健一「LablGtk2 を用いた universe teachpack の実装」日本ソフトウェア科学会第 31 回大会 (2014 年度) 講演論文集, 11 pages (September 2014). pdf (in Japanese)

11 Members

Chihiro Uehara
Kenichi Asai

This document was translated from L^AT_EX by H^EV^EA.