bashfarm

# BashFarm - Quick Start Guide

## Starting the Game

```bash

# Basic start

./game.sh

# Start with fresh game state (debug mode)

./game.sh --debug

# Use specific graphics protocol

./game.sh --protocol kitty    # Kitty graphics (best quality)

./game.sh --protocol sixel    # Sixel graphics (compatible)

./game.sh --protocol ascii    # Text-only (fastest)

```

## In-Game Controls

| Key | Action |

|-----|--------|

| `r` | Open script selection menu |

| `q` | Quit game (from main menu) |

| `Ctrl+C` | Stop running script / Quit game |

## Command-Line Options

```

--debug              Reset game state and start fresh

--protocol <type>    Force rendering protocol (kitty/sixel/ascii)

```

## Writing Your First Script

1. Create a file in `player_scripts/` with `.sh` extension:

```bash

nano player_scripts/my_first_farm.sh

```

2. Add your farming logic:

```bash

#!/bin/bash

# Move to position (0, 0)

goto 0 0

# Plant wheat

plant wheat

# Water the crop

water

# Wait for it to grow (use in loops!)

for i in {1..10}; do

    wait_tick

done

# Harvest when mature

if check_matured; then

    harvest

fi

```

3. Make it executable:

```bash

chmod +x player_scripts/my_first_farm.sh

```

4. Run the game and press `r` to select your script!

## Essential API Commands

### Cursor Control (Recommended)

```bash

goto X Y              # Move to coordinates (0-9, 0-9)

plant [crop]          # Plant seed (wheat/corn/tomato)

water                 # Water crop at cursor

harvest               # Harvest crop at cursor

check_matured         # Returns success if crop is mature

check_exists          # Returns success if crop exists

wait_tick             # Wait for next game tick

```

### Example Scripts

**Simple Single Plant:**

```bash

#!/bin/bash

goto 0 0

plant wheat

while ! check_matured; do

    water

    wait_tick

done

harvest

```

**Farm a Row:**

```bash

#!/bin/bash

# Plant row

for x in {0..4}; do

    goto $x 0

    plant wheat

done

# Water and harvest loop

while true; do

    all_done=true

    for x in {0..4}; do

        goto $x 0

        if check_exists; then

            all_done=false

            if check_matured; then

                harvest

            else

                water

            fi

        fi

    done

    wait_tick

    [ "$all_done" = true ] && break

done

```

**Farm a 3x3 Grid:**

```bash

#!/bin/bash

# See player_scripts/farm_3x3.sh for a complete example

for x in {0..2}; do

    for y in {0..2}; do

        goto $x $y

        plant wheat

    done

done

# Water loop

while true; do

    all_harvested=true

    for x in {0..2}; do

        for y in {0..2}; do

            goto $x $y

            if check_exists; then

                all_harvested=false

                if check_matured; then

                    harvest

                else

                    water

                fi

            fi

        done

    done

    wait_tick

    [ "$all_harvested" = true ] && break

done

```

## Game Mechanics Quick Reference

### Field

- 10x10 grid of farmland

- Each cell holds one crop

- Cursor visualized on screen (bright overlay)

### Crop Growth

- 6 stages: Empty → Seed → Sprout → Growing → Mature → Harvestable

- Water > 20%: Fast growth

- Water ≤ 20%: Slow growth

- Water = 0 for 10 ticks: Crop dies

- Water decreases 5% per tick

### Resources

| Crop | Points | Seeds Returned |

|------|--------|----------------|

| Wheat | 10 | 1 |

| Corn | 25 | 2 |

| Tomato | 50 | 3 |

### Starting Resources

- Seeds: 5

- Score: 0

- Tick: 0

## Tips

1. **Always use `wait_tick` in loops** - Otherwise the game can't progress

2. **Check before acting** - Use `check_exists` and `check_matured` to optimize

3. **Watch the cursor** - The visualization shows exactly where your script is working

4. **Start small** - Test with a single plant before scaling to the full grid

5. **Use echo for debugging** - Print messages to track script progress

## Troubleshooting

**Script not appearing in menu?**

- Ensure file is in `player_scripts/` directory

- File must have `.sh` extension

- Make file executable: `chmod +x player_scripts/yourscript.sh`

**Script running old code?**

- The game detects file changes and auto-restarts

- Just modify the file and run it again

- Use `--debug` flag to ensure clean state

**Graphics not working?**

- Try forcing a protocol: `./game.sh --protocol ascii`

- Check terminal compatibility (Kitty, WezTerm work best)

- ASCII mode works everywhere

**Game too fast/slow?**

- Edit `config/game.env`

- Change `TICKS_PER_SECOND` value

- Lower = slower, Higher = faster

## Configuration Files

**config/game.env** - Main game settings

```bash

TICKS_PER_SECOND=1          # Game speed

GROWTH_RATE=0.1             # Crop growth speed

RENDER_WIDTH=800            # Render width in pixels

RENDER_HEIGHT=800           # Render height in pixels

```

## Next Steps

- Read the full README.md for advanced features

- Check out example scripts in `player_scripts/`

- Experiment with different crop types

- Try to optimize for score or efficiency

- Build complex automation patterns

**Happy Farming!** 🌾