Hakk Builder

Hakk builder is an API that allows you to construct hakkML source code using Dart.

The generated source code can then be uploaded to http://hakk.it and used in competition.

What is a Hakk?

A hakk is a "program" that is specially written for the game hakk.it. Hakks compete in combat arenas against other hakks, or to complete challenges.

Basic API

The basic API provides a higher-level abstraction over the VM machine language (hakkML). It provides support for expressions, logical branching and looping. The API also provides convience functions for common hakk tasks, such as turning toward the enemy.

Using the basic API provides and easier entry point to writing hakks, but the trade-off is that the hakk will likely operate slower than hakks written in pure hakkML.

Some of the higher level constructs supported by the basic API

  • IF/ENDIF - For conditional evaluation of expressions.
  • GOSUB/RETURN - Provides a way to call subroutines, including the ability to pass parameters and get a return result.

  • WHILE/ENDWHILE - Provides a basic looping mechanism.
  • FOR/NEXT - A familiar looping construct.

Hello World

Using the basic builder API, hello world looks like this:

 hakk('hello_world');
 Block.system(0, 1);

 output("Hello World!");

 print(build());

The builder generates the following hakkML for you:

 name: "hello_world"
 blocks:
   - core:
   - mem: {name: "__sys__", loc: [0, 1]}
 code:
   core:
     - out: "Hello World!"

The basic API provides some convience capabilities for utilizing traditional higher level programming techniques. These are not robust, but sufficient enough for the scope of what hakks are intended for.

Advanced API

The advanced API exposes direct access to each instruction supported by the VM, but allows Dart's available tooling (like the Dart Editor) to help with the development process.

Hello World

Using the builder, you would construct the Hakk like this.

final myHakk = 
  hakk('hello_world', (){
    blocks((){
      B.entry('main', 0, 1);
    });
    code((){
      codeBlock('main', (){
        I.out('Hello World');
      });
    });
  })
print(myHakk);

The builder generates the hakkML and outputs:

name: hello_world
blocks:
  - core:
  - entry: {name: "main", loc : [0, 1]}
code:
  main:
    - out: "Hello World"

Saving The Result

Using the example above, this library provides a helper function to save the generated source code:

saveToFile('my_hakk', myHakk);

You could of course use dart:io to save, or do whatever else you want with the source code.

Libraries

hakkit.hakk.builder.advanced
hakkit.hakk.builder.basic
hakkit.hakk.builder.lang