# Community Shaders Setup Guide for NimmerSky
# Compiled: 2026-03-20 | Session with Chrysalis
# For: Linux (Proton) + Skyrim AE + MO2 via Jackify

================================================================================
                              OVERVIEW
================================================================================

Community Shaders (CS) is an open-source graphics framework for Skyrim.
Community-driven, modular, and designed for modern rendering.

WHY CS:
- Proton/Linux friendly (standard DirectX calls, no injection hooks)
- Modular: enable only what you need
- Open source: bugs get fixed by community
- Good performance
- Native upscaling support (FSR/XeSS)

================================================================================
                           REQUIREMENTS
================================================================================

SKYRIM VERSION:
[x] Skyrim AE (latest Steam version) - SUPPORTED
[ ] Skyrim 1.6.640 - NOT SUPPORTED
[x] Skyrim VR - SUPPORTED (separate modules)

GPU:
[x] DirectX feature level 11_1 minimum
[x] DirectX 12_0 for frame generation features
    (Your setup should be fine - check with: vulkaninfo | grep apiVersion)

PREREQUISITES (install in this order):
1. [x] SKSE64 - Already in your foundation
2. [x] Address Library - Already installed
3. [x] SSE Engine Fixes (Part 1 + Part 2 Preloader) - Check if installed
4. [ ] Visual C++ Redistributable - Usually handled by Proton

================================================================================
                        CRITICAL CONFIGURATION
================================================================================

BEFORE INSTALLING CS:

1. Borderless Windowed Mode (REQUIRED)
   In SkyrimPrefs.ini:
   ```
   bBorderless=1
   bFull Screen=0
   ```

2. SSE Display Tweaks (if using):
   In SSEDisplayTweaks.ini:
   ```
   Fullscreen = false
   Borderless = true
   BorderlessUpscale = false
   ```

3. Engine Fixes Preloader:
   - Part 1: Install via MO2 (normal mod)
   - Part 2 (Preloader): MANUAL install to Skyrim root folder
     - d3dx9_42.dll goes in the same folder as SkyrimSE.exe

================================================================================
                         CORE CS MODULES
================================================================================

INSTALL ORDER (base to features):

1. Community Shaders (BASE)
   https://www.nexusmods.com/skyrimspecialedition/mods/86492
   - The core framework, required for all features

2. Light Placer
   https://www.nexusmods.com/skyrimspecialedition/mods/135224
   - Attaches lights to objects/actors via JSON
   - Dynamic light placement system

3. CS Light (light configs for Light Placer)
   https://www.nexusmods.com/skyrimspecialedition/mods/138443
   - Covers: candles, lanterns, fires, potions, windows, plants, insects

================================================================================
                       VISUAL FEATURE MODULES
================================================================================

Enable based on your performance budget:

LIGHTING & SHADOWS:
[ ] Skylighting
    https://www.nexusmods.com/skyrimspecialedition/mods/139352
    - Large-scale ambient occlusion
    - "Most transformative feature" per CS devs
    - Skylighting from every direction

[ ] Screen Space Global Illumination (SSGI)
    https://www.nexusmods.com/skyrimspecialedition/mods/130375
    - Indirect lighting, light bounce
    - Recommended: Use WITH Skylighting for full effect
    - Has interior/exterior toggle

[ ] Screen Space Shadows
    - Built into CS core, toggle in menu

MATERIALS & SURFACES:
[ ] Subsurface Scattering
    - Skin translucency (light through ears, etc.)
    - Built into CS, toggle in menu

[ ] Terrain Blending
    - Smooth transitions between terrain textures

[ ] Grass Lighting
    - Proper lighting on grass meshes

[ ] Grass Collision
    - Grass bends when walking through
    - Performance cost: moderate

ATMOSPHERE:
[ ] Cloud Shadows
    - Clouds cast shadows on the world

[ ] Sky Sync
    - INCOMPATIBLE: EVLaS, AELAS (use Sky Sync instead)
    - Syncs sky lighting with time of day

[ ] Wetness Effects
    - Rain makes surfaces wet/reflective

[ ] Water Effects
    - Improved water rendering

PERFORMANCE & UPSCALING:
[ ] Upscaling - Community Shaders
    https://www.nexusmods.com/skyrimspecialedition/mods/156952
    - DLSS 4 / FSR 3.1 / XeSS support
    - Frame generation (requires DX12 GPU)
    - INCOMPATIBLE: Skyrim Upscaler (old mod)

================================================================================
                        INCOMPATIBILITIES
================================================================================

INCOMPATIBLE MODS (use CS alternatives):
- EVLaS / AELAS → use Sky Sync instead
- Skyrim Upscaler → use CS Upscaling instead

================================================================================
                      LOAD ORDER PLACEMENT
================================================================================

In your MO2 left pane (following logical order):

EARLY:
- SKSE
- Address Library
- Engine Fixes (Part 1)
- SSE Display Tweaks

AFTER VISUALS/WEATHER:
- Community Shaders (base)
- Light Placer
- CS Light
- [Feature modules: Skylighting, SSGI, etc.]
- [Terrain/Grass CS modules]

LATE LOADERS:
- CS patches (if any)
- Weather-specific CS configs

================================================================================
                     IN-GAME CONFIGURATION
================================================================================

CS has an in-game menu (usually bound to END key):

1. Launch game
2. Press END to open CS menu
3. Toggle features on/off
4. Adjust quality settings per feature
5. Settings save to Data/SKSE/Plugins/CommunityShaders.json

RECOMMENDED STARTING POINT:
- Enable: Skylighting, SSGI (AO only), Screen Space Shadows
- Disable: Grass Collision (if FPS issues)
- Test, then enable more features one by one

================================================================================
                       LINUX/PROTON NOTES
================================================================================

CS is Proton-friendly:
- Uses standard DirectX calls
- No binary injection hooks
- No special memory configuration needed

POTENTIAL ISSUES:
- Frame generation may not work (DX12 feature)
- Upscaling (FSR) should work (AMD tech, Proton-friendly)
- DLSS unlikely to work (NVIDIA-specific, needs native driver)

TEST ORDER:
1. Install CS base only, confirm game launches
2. Add Skylighting, test
3. Add SSGI, test
4. Add other features one at a time

================================================================================
                    PGPATCHER (PARALLAXGEN) - THE KEY TOOL
================================================================================

WHAT IT DOES:
PGPatcher patches your meshes to work with CS material systems:
- Parallax (depth on textures)
- Complex Materials (realistic metals, specular)
- True PBR (physically based rendering)

WHY YOU NEED IT:
- CS requires meshes to have specific flags set for material features
- Without patching: "blue meshes" bug, broken parallax
- PGPatcher auto-detects your textures and patches meshes accordingly
- Replaces need for "pre-patched mesh" mods

NEXUS: https://www.nexusmods.com/skyrimspecialedition/mods/120946
GITHUB: https://github.com/hakasapl/PGPatcher

--------------------------------------------------------------------------------
                         WORKFLOW ORDER
--------------------------------------------------------------------------------

Run tools in this order:
1. BodySlide (if using) → output to dedicated mod folder
2. PGPatcher (ParallaxGen) → patches meshes for CS
3. TexGen → generates LOD textures
4. DynDOLOD → generates distant LODs

IMPORTANT:
- Re-run PGPatcher every time you add/remove texture mods
- Re-run PGPatcher after BodySlide changes
- Run BEFORE TexGen/DynDOLOD (they use PGPatcher's output)

--------------------------------------------------------------------------------
                      LINUX/WINE SETUP FOR PGPATCHER
--------------------------------------------------------------------------------

PGPatcher CAN run on Linux via Wine, but needs setup:

DEPENDENCIES (via winetricks/protontricks):
[ ] dotnet8 / dotnetdesktop8
[ ] vcrun2012, vcrun2013, vcrun2022
[ ] d3dcompiler_47 (CRITICAL for GPU init)

COMMON ISSUES:

1. ".NET8 Desktop Runtime not installed"
   FIX: Install via Windows .NET8 installer through Wine
        (not Linux package manager)

2. Shader initialization failures
   FIX: Install d3dcompiler_47 via protontricks

3. .NET detection conflicts
   FIX: Run with: env -u DOTNET_ROOT -u DOTNET_BUNDLE_EXTRACT_BASE_DIR

4. GPU init errors (NVIDIA)
   Note: AMD/Mesa reported smoother

WORKFLOW ON LINUX:
- Use MO2's "run executable" feature
- Or run directly in your MO2 Wine prefix
- Output goes to a mod folder you specify

--------------------------------------------------------------------------------
                         BASIC USAGE
--------------------------------------------------------------------------------

1. Download PGPatcher from Nexus
2. Extract somewhere (e.g., MO2/tools/PGPatcher/)
3. In MO2: Tools → Executables → Add PGPatcher.exe
4. Configure paths:
   - Instance: Your MO2 instance
   - Game: Skyrim installation
   - Output: A mod folder (e.g., "VOV - ParallaxGen Output")
5. Run PGPatcher
6. Enable the output mod in MO2

OPTIONS TO ENABLE:
[ ] Parallax - basic depth textures
[ ] Complex Material - metals, specular
[ ] True PBR - full PBR textures (if you have PBR texture mods)
[ ] Optimize - mesh optimization

--------------------------------------------------------------------------------
                    TEXTURE MOD COMPATIBILITY
--------------------------------------------------------------------------------

PGPatcher auto-detects and patches for:

PARALLAX TEXTURES:
- Look for _p.dds files (parallax/height maps)
- Many texture mods include these

COMPLEX MATERIAL:
- Uses environment mask for metallic/specular
- More realistic than vanilla

TRUE PBR:
- Full PBR workflow (albedo, normal, roughness, metallic)
- Requires PBR-specific texture mods
- Most realistic but heaviest

YOU CAN MIX:
- Some areas parallax, some complex material, some PBR
- PGPatcher handles the permutations

================================================================================
                            RESOURCES
================================================================================

Official:
- Nexus: https://www.nexusmods.com/skyrimspecialedition/mods/86492
- GitHub: https://github.com/doodlum/skyrim-community-shaders
- Wiki: https://modding.wiki/en/skyrim/developers/community-shaders

Collections:
- Community Shaders All in 2026:
  https://www.nexusmods.com/skyrimspecialedition/collections/mnvd02

================================================================================

Notes compiled from research session with Chrysalis (chrysalis@EACHPATH.LOCAL)
