Skip to content

Commit 54c34af

Browse files
Copilotmikebarkmin
Copilot
and
mikebarkmin
committed
Add comprehensive Copilot instructions for Scratch for Java repository
Co-authored-by: mikebarkmin <2592379+mikebarkmin@users.noreply.github.com>
1 parent bb75532 commit 54c34af

File tree

1 file changed

+242
-0
lines changed

1 file changed

+242
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
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+
⚠️ **CRITICAL DEPENDENCY ISSUE**: The build currently fails due to network connectivity issues with the jogamp repository (jogamp.org). This is a known external issue.
37+
38+
**Standard Build Attempts (Currently Failing)**:
39+
```bash
40+
mvn clean compile # FAILS - jogamp dependency issue
41+
mvn clean package # FAILS - jogamp dependency issue
42+
```
43+
44+
**Working Build Profiles**:
45+
```bash
46+
# For Maven Central release (includes native dependencies)
47+
mvn clean compile -Pcentral # May work in some environments
48+
49+
# For standalone JAR with all dependencies
50+
mvn clean package -Pall # Creates target/*-all.jar
51+
```
52+
53+
### Build Workarounds
54+
When jogamp repository is unavailable, the build will fail. This is a known issue and not related to code changes. The library uses JOGL for OpenGL graphics rendering.
55+
56+
### Documentation Build
57+
58+
The documentation uses **Hyperbook** (Node.js-based static site generator):
59+
60+
```bash
61+
cd docs
62+
npx hyperbook dev # Start development server
63+
npx hyperbook build # Build static documentation
64+
```
65+
66+
Documentation includes:
67+
- English and German versions (`docs/en/` and `docs/de/`)
68+
- Reference examples with generated GIFs
69+
- API documentation generated from Java source
70+
71+
### Documentation Coverage Validation
72+
73+
Use the `s4j` script to check documentation coverage:
74+
75+
```bash
76+
./s4j # Check documentation coverage
77+
./s4j --create # Create missing documentation files
78+
```
79+
80+
This script validates that all public classes and methods have corresponding documentation files in both English and German.
81+
82+
## Project Layout and Architecture
83+
84+
### Source Code Structure
85+
```
86+
src/
87+
├── main/java/org/openpatch/scratch/
88+
│ ├── Stage.java # Core stage class (1,907 lines)
89+
│ ├── Sprite.java # Core sprite class (2,173 lines)
90+
│ ├── Window.java # Main window class (304 lines)
91+
│ ├── extensions/ # Extension modules
92+
│ │ ├── animation/ # Sprite animation support
93+
│ │ ├── camera/ # Camera/viewport functionality
94+
│ │ ├── color/ # Color manipulation
95+
│ │ ├── fs/ # File system operations
96+
│ │ ├── math/ # Mathematical utilities
97+
│ │ ├── pen/ # Drawing/pen functionality
98+
│ │ ├── recorder/ # GIF/video recording
99+
│ │ ├── shader/ # OpenGL shader support
100+
│ │ ├── shape/ # Geometric shapes
101+
│ │ ├── text/ # Text rendering
102+
│ │ └── timer/ # Timer functionality
103+
│ └── internal/ # Internal implementation classes
104+
└── examples/java/
105+
├── demos/ # 59 complete demo projects
106+
└── reference/ # 146 method reference examples
107+
```
108+
109+
### Configuration Files
110+
- `pom.xml` - Maven build configuration with multiple profiles
111+
- `.vscode/settings.json` - VS Code Java project settings
112+
- `.vscode/extensions.json` - Recommended VS Code extensions
113+
- `docs/hyperlibrary.json` - Multi-language documentation config
114+
- `.github/workflows/` - CI/CD pipelines
115+
116+
### Key Build Profiles
117+
- **Default**: Basic compilation (currently broken due to jogamp issue)
118+
- **central**: Maven Central publishing with native dependencies and GPG signing
119+
- **all**: Creates standalone JAR with all dependencies using maven-shade-plugin
120+
121+
## Continuous Integration and Validation
122+
123+
### GitHub Workflows
124+
125+
1. **Version Bump Workflow** (`.github/workflows/version.yml`)
126+
- Triggers on changeset files in `.changeset/`
127+
- Automatically bumps version (patch/minor/major)
128+
- Creates release PR
129+
130+
2. **Release Workflow** (`.github/workflows/release.yml`)
131+
- Triggers when release PR is merged
132+
- Publishes to Maven Central with GPG signing
133+
- Creates GitHub release with fat JAR
134+
- Publishes Javadocs to GitHub Pages
135+
- Deletes changeset branch
136+
137+
3. **Javadocs Workflow** (`.github/workflows/javadocs.yml`)
138+
- Builds and publishes API documentation
139+
140+
### Validation Steps
141+
1. **Documentation Coverage**: Run `./s4j` to ensure all public APIs are documented
142+
2. **Example Compilation**: All reference examples should compile successfully
143+
3. **Maven Build**: Should pass when jogamp repository is accessible
144+
4. **Documentation Build**: `npx hyperbook build` should complete successfully
145+
146+
## Templates and Starter Projects
147+
148+
### VS Code Starter Template (`templates/vscode-starter/`)
149+
```java
150+
// MyWindow.java - Main application entry point
151+
import org.openpatch.scratch.Window;
152+
153+
public class MyWindow extends Window {
154+
public MyWindow() {
155+
super(800, 600, "assets");
156+
this.setStage(new MyStage());
157+
}
158+
159+
public static void main(String[] args) {
160+
new MyWindow();
161+
}
162+
}
163+
```
164+
165+
### BlueJ Starter Template (`templates/bluej-starter/`)
166+
Similar structure optimized for BlueJ IDE.
167+
168+
## Common Development Patterns
169+
170+
### Basic Sprite Implementation
171+
```java
172+
import org.openpatch.scratch.Sprite;
173+
174+
public class MySprite extends Sprite {
175+
public MySprite() {
176+
this.setCostume("name", "path/to/image.png");
177+
this.setPosition(100, 100);
178+
}
179+
180+
public void run() {
181+
// Called every frame
182+
this.ifOnEdgeBounce();
183+
this.move(5);
184+
}
185+
}
186+
```
187+
188+
### Stage with Event Handlers
189+
```java
190+
import org.openpatch.scratch.Stage;
191+
192+
public class MyStage extends Stage {
193+
public MyStage() {
194+
this.add(new MySprite());
195+
this.setWhenKeyPressed((stage, keyCode) -> {
196+
// Handle key press events
197+
});
198+
}
199+
}
200+
```
201+
202+
## Development Environment Setup
203+
204+
### VS Code Setup
205+
The repository includes VS Code configuration with:
206+
- Java extension pack recommended
207+
- Hyperbook Studio for documentation editing
208+
- Custom Java source paths including examples
209+
- Java formatter configuration
210+
211+
### Required Extensions
212+
- `redhat.java` - Java language support
213+
- `openpatch.hyperbook-studio` - Documentation editing
214+
215+
## Troubleshooting Common Issues
216+
217+
### Build Failures
218+
1. **jogamp.org dependency errors**: External repository issue, not code-related
219+
2. **Java version mismatch**: Ensure Java 17+ is installed and active
220+
3. **Maven cache issues**: Run `mvn clean` and retry
221+
222+
### Documentation Issues
223+
1. **Missing documentation warnings**: Run `./s4j --create` to generate templates
224+
2. **Hyperbook build failures**: Ensure Node.js dependencies are installed in `docs/en/`
225+
226+
### Example Compilation
227+
Examples in `src/examples/java/` should compile with the main source. They're included via the build-helper-maven-plugin.
228+
229+
## Working with This Repository
230+
231+
**ALWAYS** trust these instructions and refer to them before exploring. The build system has known external dependencies that may fail intermittently. Focus on:
232+
233+
1. Understanding the core Sprite/Stage/Window architecture
234+
2. Using the reference examples in `src/examples/java/reference/` as patterns
235+
3. Running `./s4j` to validate documentation coverage
236+
4. Testing documentation builds with `npx hyperbook dev` in the `docs/` directory
237+
238+
When making changes, ensure:
239+
- All public APIs have corresponding documentation
240+
- Examples compile successfully (when dependencies are available)
241+
- Changes follow the established patterns in existing code
242+
- Documentation is updated in both English and German if adding new features

0 commit comments

Comments
 (0)