prospero.game-objects — prospero 0.1.1

This has collected convenience functions for building up game objects.

add-animator clj/s

(add-animator object [data-path change-description curve extra-args])

Add an animation to the object, specified by an animation description. See prospero.animation for more details.

add-animators clj/s

(add-animators object animators)

Add multiple animators to the object, specified by a vector of animation descriptions. See prospero.animation for more details.

add-constraints clj/s

(add-constraints object constraints)

Add a constraint from the constraints namespace to the object. The use of canned constraints makes it easier to build an entirely declarative definition of the game state.

(-> (progo/base-object game-system)
    (progo/add-constraints [::proconstraint/keep-on-screen]))

add-update-state clj/s

(add-update-state object updater-fn)

Compose an update-state function with the current chain of state updating functions. This allows the build up of per-frame behaviours to game-objects in a composable way.

(-> (progo/base-object game-system)
    (progo/update-state
      (fn [me _ _ root-state]
        ...
        me)) ; - make some modifications or send some signals
    (progo/add-update-state
      (fn [me _ _ _]
        ...
        me))) ; - add another fn around the first

This is a good way to share composable state functions.

base-object clj/s

(base-object game-system)

Create the base map for a game-object. Most game-objects will be built with this pattern:

(-> (progo/base-object game-system)
    ...)

border-radius clj/s

(border-radius object r)

Round the corners of a square box. If the object is a box, round off the corners. Likely most useful in Iris.

(-> (progo/base-object   game-system)
    (progo/bounds-box    25 25)
    (progo/colour-rgb    0 0 255)
    (progo/border-radius 3
    (progo/wireframe)) ; - make an empty blue box 25x25 with rounded corners

bounds-box clj/s

(bounds-box object width height)

Set the width and height on an object. Iris uses this as the object's physical bounds, so these values are meaningful for 2d games. Collisions are governed by the bounds-box specified in watch-collisions, so an object's hitbox can be different from its visual extent.

(-> (progo/base-object game-system)
    (progo/bounds-box  64 64)) ; - create a 64x64 square game-object

NB: future versions of Prospero are likely to introduce the concept of units to most display measurements.

children clj/s

(children object & kids)

Attach any number of child objects to the game-state.

(-> (progo/base-object game-system)
    (progo/children
      (-> (progo/base-object game-system) ...)
      (-> (progo/base-object game-system) ...)
      ...))

colour-rgb clj/s

(colour-rgb object r g b)

Request that the object have a supplied colour

(-> (progo/base-object game-system)
    (progo/colour-rgb  0 255 0)) ; - make a pure green object

NB: future versions of Prospero are likely to support more colour models this routine will likely remain safe to use, though.

colour-rgba clj/s

(colour-rgba object r g b a)

Request that the object have a supplied colour

(-> (progo/base-object game-system)
    (progo/colour-rgba 0 255 0 0.5)) ; - make a pure green object at 50% alpha

NB: future versions of Prospero are likely to support more colour models this routine will likely remain safe to use, though.

debug clj/s

(debug object)

Instruct this object to dump some of its details to whatever debug features are supported by the targeted plug-able game system. Currently this is a no-op, but is likely to see implementation in the 1.0.0 time-frame.

position-2d clj/s

(position-2d object x y)

Sets the 2d position for a game-object.

(-> (progo/base-object game-system)
    (progo/position-2d 50 50)) ; - position an object at 50, 50 pixels

NB: future versions of Prospero are likely to introduce the concept of units to most display measurements.

position-3d clj/s

(position-3d object x y z)

Set the position for an object.

(-> (progo/base-object game-system)
    (progo/position-3d 50 50 10)) ; - position an object at 50, 50, 10 pixels

NB: future versions of Prospero are likely to introduce the concept of units to most display measurements.

process-event clj/s

(process-event object event-map)

Provide a map of event descriptors to functions or prebuilt routines that can modify this object. Descriptors are vectors containing the event type and the subtype/signal. For example: [:prospero.events/keyboard-up :prospero.events/key-letter-a] The event codes will be mapped to a function taking the object/node itself, the arguments for the event, and the root-state. Event arguments are a vector: [major-event-code minor-event-code {:signal-args details}].

(-> (progo/base-object game-system)
     (progo/process-event
                      {[::proevent/keyboard-held ::proevent/key-arrow-up]
                       [proevent/change-animators-on-event {:animate-up :running}]

                       [::proevent/keyboard-up   ::proevent/key-arrow-up]
                       [proevent/change-animators-on-event {:animate-up :stopped}]

                       [::proevent/keyboard-up   ::proevent/key-space-bar]
                       (fn [me [_ _ {:keys [signal-args]}] root-state]
                          ...)}))

render-status clj/s

(render-status object status)

Setting render-status to :hidden will hide it from display. Other status values will currently display the object. Available status values and behaviours may change with the targeted plug-able game system.

(-> (progo/base-object game-system)
    (progo/render-status :hidden)) ; - hides the object from the display

rotation-2d clj/s

(rotation-2d object theta)

Set the rotation for an object in a 2d game - most meaningful for Iris.

(-> (progo/base-object game-system)
    (progo/position-3d 50 50 10) ; - position an object at 50, 50, 10 pixels
    (progo/rotation-2d 45))      ; - and rotate 45 degrees clockwise

NB: future versions of Prospero are likely to introduce the concept of units (both position and rotation) to most display measurements.

sprite-index clj/s

(sprite-index object col row)

Provide a column and row index into a sprite-sheet

(-> (progo/base-object game-system)
    (progo/sprite-sheet {:sprite-sheet-path "/my/image.png"
                         :sprite-width      64
                         :sprite-height     64
                         :columns           10
                         :rows              10}) ; - set up the image
    (progo/sprite-index 2 2)) ; - use image at column and row 2

sprite-sheet clj/s

(sprite-sheet object
              {:keys [sprite-sheet-path sprite-width sprite-height columns rows]
               :as sprite-sheet})

Make a sprite sheet available to an object. A sprite sheet describes where a texture comes from and works in conjunction with sprite-index. A sprite sheet contains a map, as such:

{:sprite-sheet-path   "/path/to/image"
   :sprite-width      a natural number specifying the width of a tile
   :sprite-height     a natural number specifying the height of a tile
   :columns           how many tile columns are in the sprite sheet
   :rows              how many rows}

text clj/s

(text object text)

Make this node a text node

(-> (progo/base-object game-system)
     (progo/text "some text to display"))

Text is likely to be incompatible with textures, sprite sheets, etc.

text-padding clj/s

(text-padding object left top right bottom)

Provide some space around a text game-object

 (-> (progo/base-object game-system)
     (progo/text-padding 10 20 10 20)) ; - build in some white-space around the text

NB: future versions of Prospero are likely to introduce the concept of units to most display measurements.

text-rgb clj/s

(text-rgb object r g b)

Request that the object have a supplied colour for its text

(-> (progo/base-object game-system)
    (progo/colour-rgb  255 255 255)
    (progo/text-rgb    0     0   0)) ; - black text on white

NB: future versions of Prospero are likely to support more colour models this routine will likely remain safe to use, though.

texture clj/s

(texture object texture-file)

Use a image file as a bitmap texture for the object.

(-> (progo/base-object game-system)
    (progo/texture     "/path"to"image.png"))

update-state clj/s

(update-state object updater-fn)

Provide a function that is called at each from to modify the state of this object. The function should be in this form:

(fn [me-the-object current-time-code frame-elapsed-time root-state])

A game-object map must be returned

(-> (progo/base-object game-system)
    (progo/update-state
      (fn [me _ _ root-state]
        ...
        me))) ; - make some modifications or send some signals

watch-collision clj/s

(watch-collision object
                 {:keys [bounds-box level-set match-set on-hit-fn reset-fn
                         offset]
                  :as cd-struct
                  :or {offset [0 0 0]}})

Call this to add a set of collision detection bounds and details to an object. Anything with collision details will be tested and a collision will be called before the object's state is updated. A collision map has the following form:

{:bounds-box  [w h]   ; -can be different from normal bounds
  :offset     [x y z] ; - offset from "left" where the bounds start
  :level-set  #{} ; - a set of collision levels this belongs on
  :match-set  #{} ; - a set of collision levels this matches with
  :on-hit-fn  (fn [me collider root-state]) ; - a fn called during collision - updates me
  :reset-fn   (fn [me])} ; - called if me is no longer colliding

watch-mutable clj/s

(watch-mutable object)

Instruct the object to observe the game's mutable state at each frame. If this is turned on, Prospero will provide a snapshot of the mutable state atom with each loop. This was the first adhoc inter-object communication system added to the engine. It's probably better to prefer watch-root and signals over this. The mutable state can be queried in :watch-mutable-state during event processing (update-state), collisions, and any other fn that takes the is passed the object as an argument.

(-> (progo/base-object game-system)
    (progo/watch-mutable)  ; - flag interest in the mutable state
    (progo/update-state    ; - write an updater that uses it
      (fn [me _ _ _] (get-in me [:watch-mutable-state]))))

NB: This seems easy to use, but it may be retired in future versions. signals and watch-root seem a mostly better option.

watch-root clj/s

(watch-root object)

Instruct the object to observe the game's evolving state at each frame of the game loop. If this is turned on, Prospero will provide a snapshot of the top of the game-object graph allowing the local node to observe the state of other objects in the graph by using get-in or similar.

(-> (progo/base-object game-system)
    (progo/watch-root)     ; - flag interest in the root state
    (progo/update-state    ; - write an updater that uses it
      (fn [me _ _ root-state] ...)))

NB: This marker must be provided for an update-state fn to receive the root-state. This restriction may be lifted in future versions, but it's probably a good practice to mark which objects look back "up" the graph.

wireframe clj/s

(wireframe object)

Do not use a fill colour, paint edges only.

(-> (progo/base-object game-system)
    (progo/bounds-box  25 25)
    (progo/colour-rgb  0 0 255)
    (progo/wireframe)) ; - make an empty blue box 25x25