@jawirhytam/kurokuro/README.md

A DjawaScript Turtle Graphics library.

# Kurokuro 🐢

A simple and fun turtle graphics library for [DjawaScript](https://github.com/gegesteorngoding/djawa-script).

With Kurokuro, you can create drawings and patterns by giving commands to a "turtle" to move on a canvas.

![Kurokuro Example Image](https://via.placeholder.com/600x300.png?text=Kurokuro+Example+Image)
*(The image above is a placeholder; you can replace it with a screenshot of your code's output)*

---

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
  - [Step 1: Initialize Your Script](#step-1-initialize-your-script)
  - [Step 2: Write Your Code](#step-2-write-your-code)
  - [Step 3: Run Your Script](#step-3-run-your-script)
- [API Reference](#api-reference)
- [Complete Example](#complete-example)

---

## Installation

To use Kurokuro, you will need two packages: `djawascript` (as the command-line tool) and `kurokuro` (the graphics library itself).

1.  **Install DjawaScript globally:**
    Open your terminal and run the following command. You might need `sudo` on Linux/macOS.

    ```bash
    npm install -g @jawirhytam/djawascript
    ```

2.  **Install Kurokuro in Your Project:**
    Create a new directory for your project, navigate into it, and install Kurokuro locally.

    ```bash
    mkdir my-kurokuro-project
    cd my-kurokuro-project
    npm install @jawirhytam/kurokuro
    ```

Now you are ready to start drawing!

## Usage

The process is very straightforward and designed to feel like running a regular script.

### Step 1: Initialize Your Script

Create a new file with a `.jawa` extension (e.g., `drawing.jawa`). To tell `djawa` that this file will use the Kurokuro graphics library, **you must** add a special comment at the very top of your file:

```djawascript
// @kurokuro: pake
```

### Step 2: Write Your Code

Use the functions from the Kurokuro API to start drawing.

```djawascript
// @kurokuro: pake

// Draw a simple square
kanggo (jarno i = 0; i < 4; i++) terus
  maju(100);
  mengen(90);
mbari
```

### Step 3: Run Your Script

Save your file, and run it using `djawa run` from your terminal.

```bash
djawa run drawing.jawa
```

An application window will appear and instantly display your drawing!

## API Reference

Here are all the commands you can give to the turtle.

| Function | Parameters | Description |
| :--- | :--- | :--- |
| `maju(distance)` | `distance: Angka` | Moves the turtle forward by `distance` pixels. |
| `mundur(distance)` | `distance: Angka` | Moves the turtle backward by `distance` pixels. |
| `mengen(degrees)` | `degrees: Angka` | Turns the turtle right by `degrees`. |
| `mengiri(degrees)` | `degrees: Angka` | Turns the turtle left by `degrees`. |
| `penMunggah()` | - | Lifts the pen up. The turtle will move without drawing. |
| `penMudun()` | - | Puts the pen down. The turtle will draw again when moving. |
| `reset()` | - | Clears all drawings on the canvas and resets the turtle to its initial position. |

## Complete Example

Here is an example to draw a hexagon.

**`hexagon.jawa`**
```djawascript
// @kurokuro: pake

// Clear the canvas and reset the turtle to the center
reset();

// Define properties for the hexagon
jarno sides = 6;
jarno sideLength = 80;
jarno angle = 360 / sides;

cetakno("Drawing a hexagon...");

// Loop to draw each side
kanggo (jarno i = 0; i < sides; i = i + 1) terus
  maju(sideLength);
  mengen(angle);
mbari

cetakno("Hexagon drawing complete!");
```

**To run it:**
```bash
djawa run hexagon.jawa
```

This will open an application window displaying the hexagon you've created.