docs: add engine reference docs for SFML3 and Raylib

[striderZA]

Summary

Adds complete engine reference documentation for SFML 3 and Raylib, bringing them to parity with the existing Godot, Unity, and Unreal engine reference sets.

Closes #78.

Changes

SFML 3 — 9 files under docs/engine-reference/sfml3/

File	Content
VERSION.md	Version pin, knowledge gap warning (SFML 3.0 released early 2025), migration overview
breaking-changes.md	SFML 2.x → 3.0 breaking changes with C++ code examples (event handling, resource loading, threading)
deprecated-apis.md	Removed classes, changed event handling, changed constructors, changed enums
current-best-practices.md	C++17 patterns, polymorphic events, CMake integration, cross-platform builds
modules/graphics.md	RenderWindow, Texture, Sprite, Shader, View
modules/audio.md	Sound, Music, SoundBuffer, Listener, spatial audio
modules/network.md	TCP/UDP sockets, Packet serialization, HTTP, FTP
modules/window.md	Polymorphic event handling, keyboard, mouse, gamepad
modules/system.md	Clock/Time, Vector2/3, std::thread, filesystem

Raylib — 10 files under docs/engine-reference/raylib/

File	Content
VERSION.md	Version pin (5.5), risk LOW, module overview
breaking-changes.md	2.x → 3.x → 4.x → 5.x version history
deprecated-apis.md	Deprecated functions with replacements
current-best-practices.md	Resource management (Load/Unload pairs), game loop, C vs C++, CMake
modules/core.md	Window, input (keyboard/mouse/gamepad), timing, file I/O
modules/rlgl.md	OpenGL abstraction, matrix stack, custom shaders, render textures
modules/raudio.md	Sound effects, music streaming, recording
modules/raymath.md	Vector2/3, Matrix, Quaternion, camera math
modules/raygui.md	Immediate-mode UI controls, styling, color picker
modules/platforms.md	Desktop, Web (Emscripten), Android, Raspberry Pi

Notes

• All files follow the established template structure from docs/engine-reference/godot/
• Each file has a "Last verified: 2026-07-22" header
• Content based on official SFML/Raylib documentation
• No changes to AGENTS.md or setup-engine skill — existing generic logic already handles these engines

[github-actions]

PR Review: feat/78-sfml3-raylib-engine-reference-docs

Overall

Well-structured, comprehensive docs. Follows the Godot reference template correctly. ~2,800 lines of well-organized content. Identified 3 bugs, 2 inconsistencies, and 2 suggestions.

---

Bugs

1. Raylib platforms.md:193 — Type mismatch (compilation error)

Vector3 worldPos = GetScreenToWorldRay(mousePos, camera);

GetScreenToWorldRay() returns a Ray, not a Vector3. This won't compile. The subsequent .direction access on line 196 confirms a Ray was intended. Fix: use Ray ray = GetScreenToWorldRay(...).

2. Raylib raudio.md:78-80 — Duplicate SetMusicVolume (copy-paste error)

// Looping
SetMusicVolume(bgm, 0.7f);
// Music loops by default

The comment says "Looping" but the line calls SetMusicVolume again (already set on line 74). Should be something like a looping property or removed entirely.

3. Raylib raymath.md:10 — Factual error about raymath.h

"Include raymath.h separately or use the functions built into raylib.h"

raymath functions are not built into raylib.h. They require a separate #include "raymath.h". This is misleading — a programmer following this advice would get linker errors.

---

Inconsistencies

4. Texture2D vs Texture type name

• raylib/deprecated-apis.md:21 says Texture2D is deprecated, use Texture
• raylib/current-best-practices.md:12,20,24 all use Texture2D in code examples

Fix: align best-practices examples to use Texture as recommended.

5. SFML3 resource loading pattern in graphics.md:87-88

sf::Shader shader;
shader.loadFromFile("assets/shader.vert", "assets/shader.frag");

All other SFML 3.0 resources (Texture, SoundBuffer, Font) use constructor-based loading with exceptions. But shaders use the old loadFromFile pattern. If SFML 3.0 also moved shaders to constructors, this is inconsistent. Verify and align.

---

Suggestions

6. Generic package name (raylib/platforms.md:253)

const char* savePath = "/data/data/com.game/save.dat";

com.game is a placeholder. Suggest using a more realistic example like com.studio.gamename to avoid someone copying it verbatim.

7. Vague guidance (sfml3/breaking-changes.md:108)

"getDefaultView() API unchanged but verify usage patterns"

This doesn't tell the reader what to verify or why. Either remove the line or replace with a concrete note about what changed in view handling (if anything).

---

Positive Notes

• Excellent template alignment with the existing Godot reference
• Clear, consistent code examples throughout
• "Common Mistakes" sections in every module file are practical and relevant
• Knowledge gap warnings are accurate and appropriately visible
• Good migration path guidance (2.x→3.0) with before/after code pairs

opencode session  |  github run

[github-actions]

User github-actions[bot] does not have write permissions

github run

[github-actions]

PR Review: feat/78-sfml3-raylib-engine-reference-docs

Previous Review Fixes

The 7 issues from the automated review have been resolved in commit 08ca88d:

• GetScreenToWorldRay return type corrected to Ray
• Duplicate SetMusicVolume removed from raudio.md
• raymath.h bundled claim corrected (it's NOT bundled)
• All Texture2D → Texture type references fixed
• Shader loadFromFile() exception documented with explanation
• com.game → com.studio.gamename placeholder fixed
• View API description made concrete

Still Open Issues

1. sfml3/modules/network.md:14-15 — Factual error: sf::Http and sf::Ftp removed in 3.0

- `sf::Http`, `sf::Ftp` for high-level protocols remain

These were removed in SFML 3.0. The migration guidance should recommend alternatives (e.g., cpp-httplib, libcurl). Line 9 ("API surface mostly unchanged") also needs updating since HTTP/FTP removal is a notable surface change.

2. CHANGELOG.md and CHANGELOG_INTERNAL.md — Duplicate unreleased sections
The PR adds a second (and third) Update unreleased — 2026-07-22 section in CHANGELOG.md and a second [unreleased] — 2026-07-22 in CHANGELOG_INTERNAL.md, duplicating entries that already exist further down in each file.

3. docs/engine-reference/raylib/VERSION.md:7 — Release date may be off
States "Release Date: 2025" for Raylib 5.5. Raylib 5.5 was released November 2024. Worth verifying.

Additional Observations

• All 19 engine reference files follow the Godot template structure correctly
• Code examples are consistent, well-commented, and use current API patterns
• "Common Mistakes" sections in every module file are practical and relevant
• The SFML3 content accurately reflects the major 2.x→3.0 breaking changes (polymorphic events, constructor-based loading, C++17 requirement)
• The Raylib content correctly covers its five modules plus platform-specific considerations

opencode session  |  github run