Technical Specification Snapshot
| Parameter | Description |
|---|---|
| Language | Java (Processing IDE and core implementation) |
| Configuration Format | Java Properties |
| Key Mechanism | sketch.properties + main= |
| Relevant Versions | Processing 4.0 Beta 6 and later |
| Compatibility Strategy | Falls back to the traditional same-name rule when main= is missing |
| Core Dependencies | Sketch.java, SketchCode.java, handleOpen() |
| Reference Popularity | The original source did not provide a star count; the core repository is processing/processing4 |
Processing 4 upgrades the main sketch entry from a strict convention to a configurable convention
For years, Processing sketches followed one hard rule: the folder name had to match the main .pde file. In other words, the MySketch/ directory had to contain MySketch.pde for the IDE to recognize and open the project correctly.
That rule was simple and intuitive, but it was not ideal for modern development workflows. In Git refactoring, branch-based experiments, and cross-platform entry switching, tightly binding the directory name to the entry file increases maintenance costs.
The difference between the traditional structure and the new structure is clear
# Traditional structure: folder name is tightly bound to the main sketch name
MySketch/
├── MySketch.pde
└── Helper.pde
# New structure: specify the main entry through sketch.properties
MySketch/
├── sketch.properties
├── Entry.pde
└── Helper.pdeThis structural comparison shows that after Processing 4, the main sketch resolution logic no longer relies only on filename inference. It now reads configuration first and falls back to convention second.
The core purpose of sketch.properties is to explicitly declare sketch metadata
sketch.properties is fundamentally a standard Java Properties file. Originally, it mainly carried sketch mode information such as mode.id= or mode=, which tells the IDE which mode the project runs in.
Starting with Processing 4.0 Beta 6, this file gained a more important capability: you can use main= to specify the main sketch file explicitly. As a result, the IDE no longer has to treat folder-name.pde as the only valid entry point when opening a project.
The minimum usable configuration is a single line
main=GameEngine.pdeThis line tells the IDE to use GameEngine.pde as the main tab and primary entry point instead of inferring it automatically from the folder name.
The IDE reads the main configuration first when opening a project
Based on the source material, this change is directly tied to the rewrite of handleOpen(). The new flow can be summarized in three steps: load sketch.properties, parse main=, and then build the code file list while setting tab order.
If main= exists, the specified file becomes the first main tab. The remaining .pde files continue to function as supporting code tabs, usually sorted by name. This means both entry-point detection and IDE presentation were updated in a unified way.
Pseudocode summarizes this behavior well
// Read the sketch configuration file first
Properties props = loadSketchProperties(sketchFolder);
// Prefer main; fall back to the traditional rule when missing
String mainFileName = props.getProperty("main", sketchName + ".pde");
// Construct the main sketch file object
File mainFile = new File(sketchFolder, mainFileName);This logic reflects an important design shift: configuration overrides convention, while backward compatibility remains intact.
This mechanism directly improves version control and project organization
For everyday developers, the biggest benefit is not simply that you can rename files. The real gain is that project structure can finally serve the development workflow instead of forcing the workflow to serve IDE constraints.
For example, you can let the folder name express version semantics, experiment status, or platform differences while keeping the main sketch file name stable. That reduces file moves during refactoring and lowers the risk of breaking Git history continuity.
A typical multi-entry example
# Windows entry point
main=Main_Windows.pde# macOS entry point
main=Main_Mac.pdeThis switching approach works well for demo projects, platform-adaptation projects, and teaching samples. It does not necessarily amount to a complete multi-entry system, but it already provides a practical foundation for separating entry points.
Important boundary conditions still apply
First, if main= is missing, Processing still falls back to the traditional same-name rule, so older projects continue to run without migration. Second, whether command-line tools and third-party extensions fully support this behavior depends on whether they have implemented the new resolution logic as well.
Third, when exporting an application, the final artifact name may not always follow main= exactly. Some build pipelines may still prefer the folder name or project name, so you should validate this explicitly in automated release workflows.
Start with a minimal test project to verify behavior
DemoProject/
├── sketch.properties
├── DemoMain.pde
├── Utils.pde
└── README.mdmain=DemoMain.pdeThis minimal setup is enough to verify whether the IDE recognizes the main entry correctly, whether tab ordering matches expectations, and whether third-party tooling remains compatible.
From an architectural perspective, this is a pragmatic concession to modern workflows
Processing originated in an earlier era, and many of its design decisions prioritized a low learning curve, simple conventions, and immediate usability. Binding the main sketch name to the directory name is a classic example of that philosophy.
But once projects become modular, collaborative, and versioned, overly strict conventions start to create engineering friction. The main= mechanism in sketch.properties does not discard the old model. Instead, it preserves the beginner-friendly experience while adding the flexibility advanced users need.
FAQ
1. Has Processing 4 completely removed the requirement that the folder name must equal the main sketch name?
No. It has not removed the rule entirely. Instead, the rule is now “follow the default convention unless configuration overrides it.” If sketch.properties or main= is absent, Processing still uses the traditional same-name behavior.
2. Must main= include the .pde extension?
Based on the available material, it is best to specify the full filename explicitly, such as main=Entry.pde. Whether the extension can be omitted or whether relative paths are supported depends on the exact source version and real-world testing.
3. Will third-party tools and VS Code extensions support this mechanism automatically?
Not necessarily. Some toolchains may still validate the main file using the old rule, so you should test the IDE, command-line tools, export pipeline, and extension environment separately.
References
- Processing 4 Beta 6 release notes:
handleOpen()rewrite details sketch.propertiesexamples in the official Processing documentation repository- Processing 4 source code:
Sketch.java,SketchCode.java,JavaBuild.java - Discussions on Processing Discourse about
sketch.propertiesand multi-.pdefile behavior
AI Visual Insight: This animated image is a WeChat sharing prompt from the blogging platform. It is part of the content distribution UI rather than the technical subject itself, and it does not show Processing project structure, IDE behavior, or source code details. As a result, it does not carry technical information directly related to the sketch.properties mechanism.
AI Readability Summary
This article explains the sketch.properties mechanism introduced in Processing 4, with a focus on how the main= setting removes the long-standing restriction that the main sketch file must match the folder name. It also clarifies the practical value of this change for version control, multi-entry project layouts, and modern development workflows.