Previous Chapter: Asset Control Flow

Next Chapter: Asset Control Flow

Main Page

Kdl is the official file format used by Mischief.

The KdlAsset typeclass is a helper for defining assets that are loaded from .kdl files without needing to parse their fields manually.

Generally, only types with named fields (records) can automatically derive it:

data Foo = Foo
  {
    a :: Int
    b :: Float
    c :: V2 Int
  }
  deriving (Generic, KdlAsset)

You can now use the loadKdl function provided by the typeclass to quickly make a loadable asset:

instance Asset Foo where
  type Saveable Foo = False

  loadAsset = loadKdl "foo"

The asset itself should look something like this:

foo {
  a 6
  b 3.2
  c 2 4
}

You can write custom kdl decoders using the kdl-hs library.

For instance, this is how you could decode the asset from the previous section:

instance KdlAsset Foo where
  decodeKdl path = KDL.children $ do
    a <- KDL.argAt "a"
    b <- KDL.argAt "b"
    c <- KDL.nodeWith "c" KDL.nodeDecoder
    pure $ Foo {a, b, c}

Note that here we can use "KDL.nodeDecoder" because V2 a has a KDL.DecodeNode instance. Otherwise you'd need to parse it manually, like the others.

The path argument is used to decode references to other assets. For instance, if Foo also had this field:

bar :: AssetRef Bar

You'd decode it like this:

bar <- argAtWith $ "bar" $ decodeRef path

For KdlRefs you use decodeKdlRef instead.

A Kdl Collection is a map of nodes of the same type.

For instance, this field:

a :: KdlCollection Int

Expects something that looks like this:

a {
  name1 4
  name2 6
  name3 5
  ...
}

You can use colGet to try and get the value of a node from a collection by name. Or colGetMany to get the value of all nodes with the given name.