project-structure.md

Project Structure

Language: English | 简体中文

Repository root

Path	Role in Alpha Piscium
shaders/	Runtime shader-pack contents that can be installed directly
scripts/	Generators, packaging, release, and offline asset tools
docs/	Project-specific development and module documentation
changelogs/	Release notes; the options script also derives its default version from them
data/	Source data used by offline scripts
licenses/	Third-party licenses shipped in the package
.github/	GitHub workflows and repository configuration
README.md, LICENSE	Public overview and primary license

shaders/

shaders/
├─ Base.glsl      common include root
├─ base/          shared interfaces and generated bindings
├─ pass/          entry-point shaders grouped by pipeline stage
├─ techniques/    reusable modules plus existing direct compute entries
├─ util/          general GLSL helpers and data types
├─ textures/      runtime LUT, noise, sky, cloud, and sampling assets
├─ lang/          generated option localization
├─ *.csh          generated compute wrappers
├─ *.vsh/*.fsh…   Iris compatibility entry wrappers
├─ shaders.properties
└─ shadesmith.json

Base.glsl and base/

• shaders/Base.glsl is the common include root for most shaders. It brings in the compatibility, uniform, texture, SSBO, and option interfaces under base/; utilities are included separately as needed.
• Uniforms.glsl, Textures.glsl, and SSBO.glsl define the project's shared data bindings. Configs.glsl separately defines Iris/shadow compatibility, attachment-clear behavior, and retains a format reference table in its comments.
• Options.glsl and TextOptions.glsl are generated by the options DSL.
• Textile.glsl carries Shadesmith tile bindings; shadesmith.json is the source of the tile layout.

pass/

Only shaders with an entry point belong here; it is the standard location for new entry points:

• setup/: initialization and cleanup when the shader pack loads or its dimensions change.
• begin/: per-frame global-data, LUT, work-queue, and transient-resource preparation.
• geometry/: solid, translucent, and shadow geometry entry implementations.
• shadowcomp/: water-normal processing after shadow geometry.
• composite/: screen-space lighting, GI, volumetrics, translucency, and post-processing entry points.
• general/: shared full-screen and no-op wrapper implementations.

Shared code without main belongs under techniques/ or util/.

techniques/

This directory groups reusable implementations by algorithm or module. It also currently retains a few compute entry points registered directly in the program list, including Bloom.comp.glsl, rtwsm/*.comp.glsl, and atmospheric LUT/cloud passes:

• gi/: shared ReSTIR, reprojection, reservoir, and GI-denoising implementations; the SST core is SST2.glsl at the technique root.
• atmospherics/: atmospheric-scattering LUTs, epipolar scattering, underwater volumetrics, and clouds.
• rtwsm/: shadow importance maps, warping, and coordinate mapping.
• displaytransform/: exposure, DRT, and final display transforms.
• ffx/: the FSR1/RCAS/SPD code currently in use and third-party compatibility layers.
• Files at the directory root include shared bloom, DOF, Hi-Z, lighting, environment-probe, and water-wave implementations.

Treat the existing direct compute entries as existing layout, not as a template for new entry points.

util/

This directory contains helpers that are genuinely shared across modules: math, coordinate, sampling, random-number, material/G-buffer, BSDF/Fresnel, and color-space utilities. Debug implementations live under shaders/techniques/debug/. Code used by one major module should stay in its corresponding techniques/<module>/ directory rather than expanding the shared layer.

Root wrappers and properties

• setup*.csh, begin*.csh, shadowcomp*.csh, and composite*.csh are generated by scripts/programs.main.kts.
• gbuffers_*, shadow*, dh_*, and final.* are Iris compatibility entry points that include the real implementations under pass/.
• shaders.properties is generated; maintain scripts/shaders.properties and the program/options source files instead.
• block.properties supplies block material/emissive mappings. item.properties currently contains only item.0=air, which controls held-item/empty-hand ID behavior.
• voxy*.glsl and voxy.json are Voxy integration entry points. Voxy implements voxy_emitFragment directly and does not include the general geometry pass.

scripts/

The core generation chain is programs.main.kts, options.main.kts, shadesmith.ps1, and make-zip.main.kts. The remaining *.kts/*.main.kts files mainly generate offline textures/LUTs or perform release operations; see other scripts. scripts/shaders.properties is a handwritten property source, not generated output.

Placement rules

• New entry points with main: shaders/pass/; without main: shaders/techniques/ or shaders/util/. Maintain existing technique compute entries in place unless a dedicated structure refactor moves them.
• Reuse an existing module directory unless a genuinely separate pipeline responsibility appears.
• Update generated files through their source script.
• New settings go through the options DSL, tiles through shadesmith.json, and compute passes through the program list.