FTC-Project-Gen/README.md

# FTC Project Generator

Generate clean, testable FTC robot projects. Keep YOUR code separate from the FTC SDK bloat.

## Philosophy

**Normal FTC Way:** Clone their repo, modify their code  
**This Way:** Your code is clean, FTC SDK is just a dependency

One shared SDK, multiple clean projects. Test on PC, deploy when ready.

## Quick Start

```bash
# Create your first project
./ftc-new-project my-robot

# Create another project (reuses same SDK!)
./ftc-new-project another-bot

# Use specific FTC version
./ftc-new-project test-bot --version v10.0.0
```

## What It Does

1. **Checks/clones FTC SDK** (once, shared across projects)
2. **Creates YOUR clean project** with:
   - Minimal structure
   - Test scaffolding
   - Example subsystem
   - Composite build to SDK
3. **Ready to code** - tests run immediately

## Generated Project Structure

```
my-robot/
├── build.gradle.kts          # Your build (references SDK)
├── settings.gradle.kts       # Composite build setup
├── gradlew                   # Gradle wrapper
├── README.md                 # Project-specific docs
└── src/
    ├── main/java/robot/
    │   ├── Pose2d.java              # Utility classes
    │   ├── subsystems/
    │   │   └── Drive.java           # Example subsystem
    │   ├── hardware/
    │   │   └── MecanumDrive.java    # Hardware impl stub
    │   └── opmodes/
    │       └── TeleOp.java          # FTC OpMode
    └── test/java/robot/
        └── subsystems/
            └── DriveTest.java       # Unit test

Separate (shared):
~/ftc-sdk/                    # FTC SDK (one copy for all projects)
```

## Usage

### Development (Day-to-Day)

```bash
cd my-robot

# Run tests
./gradlew test

# Watch mode (auto-rerun on save)
./gradlew test --continuous

# Write code, tests pass → you're good!
```

### Deployment (When Ready for Robot)

```bash
# 1. Deploy your code to SDK
./gradlew deployToSDK

# 2. Build APK
cd ~/ftc-sdk
./gradlew build

# 3. Install to robot
# Use Android Studio's deploy button, or:
adb install FtcRobotController/build/outputs/apk/debug/FtcRobotController-debug.apk
```

## Multiple Projects

The beauty: **one SDK, many projects**

```bash
# Create project 1
./ftc-new-project swerve-bot

# Create project 2 (reuses SDK!)
./ftc-new-project mecanum-bot

# Create project 3 (still same SDK!)
./ftc-new-project test-chassis
```

Each project:
- Has its own git repo
- Tests independently
- Deploys to shared SDK
- Can have different license
- Is YOUR code, not FTC's

## Commands Reference

```bash
# Basic usage
./ftc-new-project <name>

# Specify FTC version
./ftc-new-project <name> --version v10.1.1

# Custom SDK location
./ftc-new-project <name> --sdk-dir ~/my-ftc

# Get help
./ftc-new-project --help
```

## Environment Variables

```bash
# Set default SDK location
export FTC_SDK_DIR=~/ftc-sdk

# Now just:
./ftc-new-project my-robot
```

## Pattern: Subsystems

Every generated project follows this pattern:

```java
// Your subsystem
public class MySubsystem {
    private final Hardware hardware;
    
    public MySubsystem(Hardware hardware) {
        this.hardware = hardware;
    }
    
    // Business logic here - tests on PC
    public void doSomething() {
        hardware.doThing();
    }
    
    // Inner interface - implement for robot
    public interface Hardware {
        void doThing();
    }
}

// Test (inline mock)
class MySubsystemTest {
    static class MockHardware implements MySubsystem.Hardware {
        boolean didThing = false;
        public void doThing() { didThing = true; }
    }
    
    @Test
    void test() {
        MockHardware mock = new MockHardware();
        MySubsystem sys = new MySubsystem(mock);
        sys.doSomething();
        assertTrue(mock.didThing);
    }
}

// Hardware impl (for robot)
public class RealHardware implements MySubsystem.Hardware {
    private DcMotor motor;
    
    public RealHardware(HardwareMap map) {
        motor = map.get(DcMotor.class, "motor");
    }
    
    public void doThing() {
        motor.setPower(1.0);
    }
}
```

## Why This Is Better

**Traditional FTC:**
- Clone 200MB repo
- Your code mixed with SDK
- Hard to test
- Hard to share
- Stuck with their structure

**This Way:**
- Your project: ~50KB
- SDK: shared, separate
- Easy to test (runs on PC)
- Easy to share (just your code)
- Your structure, your license

## FAQ

**Q: Can I use multiple FTC versions?**  
A: Yes! Different projects can reference different SDK dirs.

**Q: What if I want to update the SDK?**  
A: `cd ~/ftc-sdk && git pull && git checkout v10.2.0`  
   Or specify new version when creating project.

**Q: Does this work with Android Studio?**  
A: For deployment, yes. For development, use whatever you want (Sublime, vim, etc).

**Q: Can I put my project on GitHub with a different license?**  
A: Yes! Your code is separate. Just don't include SDK files.

**Q: What about Control Hub having multiple programs?**  
A: Each project creates OpModes. Deploy multiple projects to SDK, build once, all show up on Control Hub.

## Installation

```bash
# Extract the generator
tar xzf ftc-project-generator.tar.gz
cd ftc-project-gen

# Option 1: Run install script (recommended)
./install.sh             # Shows options
sudo ./install.sh        # System-wide install

# Option 2: Manual symlink
sudo ln -s $(pwd)/ftc-new-project /usr/local/bin/

# Option 3: Add to PATH
echo "export PATH=\$PATH:$(pwd)" >> ~/.bashrc
source ~/.bashrc

# Verify installation
ftc-new-project --help
```

## The Magic

When you run tests, your code uses **interfaces** and **mocks** - no FTC SDK needed.

When you deploy, your code gets copied to SDK's TeamCode and built with the real FTC libraries.

Your code stays clean. SDK is just a build tool.

## Example Session

```bash
# Create project
$ ./ftc-new-project my-bot
>>> Checking FTC SDK...
SDK directory exists, checking version...
✓ SDK already at version v10.1.1
>>> Creating project: my-bot
✓ Project created: my-bot

# Develop
$ cd my-bot
$ ./gradlew test
BUILD SUCCESSFUL
2 tests passed

# Add code, tests pass...

# Ready to deploy
$ ./gradlew deployToSDK
Code deployed to TeamCode - ready to build APK

$ cd ~/ftc-sdk
$ ./gradlew build
BUILD SUCCESSFUL

# Install to robot...
```

Clean, simple, modular. As it should be.

## Credits

Built by frustrated mentors who think the standard FTC setup is backwards.

## License

MIT - do whatever you want. Unlike FTC's forced BSD license nonsense.