Skip to content

Commit f4fb57c

Browse files
mikebarkminmikebarkmin
authored
Merge pull request #12 from openpatch/copilot/fix-c0b52253-9a35-4c70-a271-3bc63c55e9ed
Add comprehensive Copilot instructions for repository onboarding
2 parents e0d9005 + 135ccfa commit f4fb57c

File tree

1 file changed

+240
-0
lines changed

1 file changed

+240
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# Copilot Instructions for Scratch for Java
2+
3+
## Repository Overview
4+
5+
**Scratch for Java** is a Java library that replicates the functionality and concepts of Scratch, helping learners transition from block-based programming to text-based coding in Java. The library provides an approachable API inspired by Scratch blocks, making it easier for beginners to understand programming concepts while gaining experience with real Java syntax and tools.
6+
7+
- **Main Package**: `org.openpatch.scratch`
8+
- **Current Version**: 4.24.1
9+
- **Java Version**: 17
10+
- **Build Tool**: Maven
11+
- **Documentation Site**: https://scratch4j.openpatch.org
12+
- **Repository Size**: ~5,500 lines of core Java code, 146 reference examples, 59 demo projects
13+
14+
## High-Level Architecture
15+
16+
The library is structured around three core concepts:
17+
1. **Window**: The main application window (extends `Window` class)
18+
2. **Stage**: The game/application stage where sprites and elements are displayed
19+
3. **Sprite**: Interactive objects that can move, detect collisions, play sounds, etc.
20+
21+
### Key Dependencies
22+
- **Processing 4.4.6**: Core graphics and windowing framework
23+
- **Jackson 2.19.2**: JSON/XML processing
24+
- **JOGL 2.5.0**: OpenGL bindings (from jogamp repository)
25+
- **Gluegen 2.5.0**: Native library loading
26+
27+
## Build Instructions and Known Issues
28+
29+
### Prerequisites
30+
- Java 17+ (verified with OpenJDK 17.0.16)
31+
- Maven 3.9.11+
32+
- Node.js + npm (for documentation)
33+
34+
### Maven Build Commands
35+
36+
**Standard Build Commands**:
37+
```bash
38+
mvn clean compile # Basic compilation
39+
mvn clean package # Create standard JAR
40+
mvn clean test # Run tests (if any)
41+
```
42+
43+
**Build Profiles**:
44+
```bash
45+
# For Maven Central release (includes native dependencies)
46+
mvn clean compile -Pcentral
47+
48+
# For standalone JAR with all dependencies
49+
mvn clean package -Pall # Creates target/*-all.jar
50+
```
51+
52+
**Note**: The library uses JOGL for OpenGL graphics rendering, which requires access to the jogamp.org repository. This dependency is now working correctly in the CI environment.
53+
54+
### Documentation Build
55+
56+
The documentation uses **Hyperbook** (Node.js-based static site generator):
57+
58+
```bash
59+
cd docs
60+
npx hyperbook dev # Start development server
61+
npx hyperbook build # Build static documentation
62+
```
63+
64+
Documentation includes:
65+
- English and German versions (`docs/en/` and `docs/de/`)
66+
- Reference examples with generated GIFs
67+
- API documentation generated from Java source
68+
69+
### Documentation Coverage Validation
70+
71+
Use the `s4j` script to check documentation coverage:
72+
73+
```bash
74+
./s4j # Check documentation coverage
75+
./s4j --create # Create missing documentation files
76+
```
77+
78+
This script validates that all public classes and methods have corresponding documentation files in both English and German.
79+
80+
## Project Layout and Architecture
81+
82+
### Source Code Structure
83+
```
84+
src/
85+
├── main/java/org/openpatch/scratch/
86+
│ ├── Stage.java # Core stage class (1,907 lines)
87+
│ ├── Sprite.java # Core sprite class (2,173 lines)
88+
│ ├── Window.java # Main window class (304 lines)
89+
│ ├── extensions/ # Extension modules
90+
│ │ ├── animation/ # Sprite animation support
91+
│ │ ├── camera/ # Camera/viewport functionality
92+
│ │ ├── color/ # Color manipulation
93+
│ │ ├── fs/ # File system operations
94+
│ │ ├── math/ # Mathematical utilities
95+
│ │ ├── pen/ # Drawing/pen functionality
96+
│ │ ├── recorder/ # GIF/video recording
97+
│ │ ├── shader/ # OpenGL shader support
98+
│ │ ├── shape/ # Geometric shapes
99+
│ │ ├── text/ # Text rendering
100+
│ │ └── timer/ # Timer functionality
101+
│ └── internal/ # Internal implementation classes
102+
└── examples/java/
103+
├── demos/ # 59 complete demo projects
104+
└── reference/ # 146 method reference examples
105+
```
106+
107+
### Configuration Files
108+
- `pom.xml` - Maven build configuration with multiple profiles
109+
- `.vscode/settings.json` - VS Code Java project settings
110+
- `.vscode/extensions.json` - Recommended VS Code extensions
111+
- `docs/hyperlibrary.json` - Multi-language documentation config
112+
- `.github/workflows/` - CI/CD pipelines
113+
114+
### Key Build Profiles
115+
- **Default**: Basic compilation (currently broken due to jogamp issue)
116+
- **central**: Maven Central publishing with native dependencies and GPG signing
117+
- **all**: Creates standalone JAR with all dependencies using maven-shade-plugin
118+
119+
## Continuous Integration and Validation
120+
121+
### GitHub Workflows
122+
123+
1. **Version Bump Workflow** (`.github/workflows/version.yml`)
124+
- Triggers on changeset files in `.changeset/`
125+
- Automatically bumps version (patch/minor/major)
126+
- Creates release PR
127+
128+
2. **Release Workflow** (`.github/workflows/release.yml`)
129+
- Triggers when release PR is merged
130+
- Publishes to Maven Central with GPG signing
131+
- Creates GitHub release with fat JAR
132+
- Publishes Javadocs to GitHub Pages
133+
- Deletes changeset branch
134+
135+
3. **Javadocs Workflow** (`.github/workflows/javadocs.yml`)
136+
- Builds and publishes API documentation
137+
138+
### Validation Steps
139+
1. **Documentation Coverage**: Run `./s4j` to ensure all public APIs are documented
140+
2. **Example Compilation**: All reference examples should compile successfully
141+
3. **Maven Build**: Standard build commands work with all profiles
142+
4. **Documentation Build**: `npx hyperbook build` should complete successfully
143+
144+
## Templates and Starter Projects
145+
146+
### VS Code Starter Template (`templates/vscode-starter/`)
147+
```java
148+
// MyWindow.java - Main application entry point
149+
import org.openpatch.scratch.Window;
150+
151+
public class MyWindow extends Window {
152+
public MyWindow() {
153+
super(800, 600, "assets");
154+
this.setStage(new MyStage());
155+
}
156+
157+
public static void main(String[] args) {
158+
new MyWindow();
159+
}
160+
}
161+
```
162+
163+
### BlueJ Starter Template (`templates/bluej-starter/`)
164+
Similar structure optimized for BlueJ IDE.
165+
166+
## Common Development Patterns
167+
168+
### Basic Sprite Implementation
169+
```java
170+
import org.openpatch.scratch.Sprite;
171+
172+
public class MySprite extends Sprite {
173+
public MySprite() {
174+
this.setCostume("name", "path/to/image.png");
175+
this.setPosition(100, 100);
176+
}
177+
178+
public void run() {
179+
// Called every frame
180+
this.ifOnEdgeBounce();
181+
this.move(5);
182+
}
183+
}
184+
```
185+
186+
### Stage with Event Handlers
187+
```java
188+
import org.openpatch.scratch.Stage;
189+
190+
public class MyStage extends Stage {
191+
public MyStage() {
192+
this.add(new MySprite());
193+
this.setWhenKeyPressed((stage, keyCode) -> {
194+
// Handle key press events
195+
});
196+
}
197+
}
198+
```
199+
200+
## Development Environment Setup
201+
202+
### VS Code Setup
203+
The repository includes VS Code configuration with:
204+
- Java extension pack recommended
205+
- Hyperbook Studio for documentation editing
206+
- Custom Java source paths including examples
207+
- Java formatter configuration
208+
209+
### Required Extensions
210+
- `redhat.java` - Java language support
211+
- `openpatch.hyperbook-studio` - Documentation editing
212+
213+
## Troubleshooting Common Issues
214+
215+
### Build Failures
216+
1. **Maven cache issues**: Run `mvn clean` and retry
217+
2. **Java version mismatch**: Ensure Java 17+ is installed and active
218+
3. **Dependency download issues**: Check network connectivity and retry
219+
220+
### Documentation Issues
221+
1. **Missing documentation warnings**: Run `./s4j --create` to generate templates
222+
2. **Hyperbook build failures**: Ensure Node.js dependencies are installed in `docs/en/`
223+
224+
### Example Compilation
225+
Examples in `src/examples/java/` should compile with the main source. They're included via the build-helper-maven-plugin.
226+
227+
## Working with This Repository
228+
229+
**ALWAYS** trust these instructions and refer to them before exploring. Focus on:
230+
231+
1. Understanding the core Sprite/Stage/Window architecture
232+
2. Using the reference examples in `src/examples/java/reference/` as patterns
233+
3. Running `./s4j` to validate documentation coverage
234+
4. Testing documentation builds with `npx hyperbook dev` in the `docs/` directory
235+
236+
When making changes, ensure:
237+
- All public APIs have corresponding documentation
238+
- Examples compile successfully
239+
- Changes follow the established patterns in existing code
240+
- Documentation is updated in both English and German if adding new features

0 commit comments

Comments
 (0)