122 lines
4.7 KiB
Markdown
122 lines
4.7 KiB
Markdown
# Codex Project File Setup Manual
|
|
|
|
This note records how `HyperTwist` should be represented in Visual Studio while the codebase is still being assembled.
|
|
|
|
## Current Supersession - 2026-07-26
|
|
|
|
HyperTwist now has a real Unreal application root. The tracked authority is:
|
|
|
|
- `UnrealHyperTwist/UnrealHyperTwist.uproject`
|
|
- `UnrealHyperTwist/Source/`
|
|
- `UnrealHyperTwist/Config/`
|
|
|
|
The ignored repo-root `HyperTwist.sln`, `HyperTwist.vcxproj`,
|
|
`HyperTwist.vcxproj.filters`, and `HyperTwist.vcxproj.user` files were retired
|
|
after the root project became the exact giant file collector prohibited below.
|
|
They indexed custody snapshots, mirrors, and generated Unreal output and were
|
|
not a valid build surface.
|
|
|
|
For normal work, open the `.uproject`. Visual Studio or Unreal may generate
|
|
`UnrealHyperTwist/UnrealHyperTwist.sln` and related `Intermediate/ProjectFiles`
|
|
state on a Windows host when needed. Those generated files remain disposable
|
|
IDE state and are not source authority.
|
|
|
|
The historical guidance below remains useful as the reason not to recreate a
|
|
repo-root catch-all project.
|
|
|
|
## Current Rule
|
|
|
|
The repo-root `HyperTwist.vcxproj` should be treated as a lightweight workspace shell, not as the real application project.
|
|
|
|
It should not be used to pull in large repository trees such as:
|
|
|
|
- `mirrors/`
|
|
- `node_modules/`
|
|
- generated output such as `.vs/`, `x64/`, `Intermediate/`, `Binaries/`, `dist/`, `coverage/`
|
|
- research, archives, downloads, or reference bundles
|
|
|
|
If the root `.vcxproj` turns into a giant file collector, Visual Studio indexing, Copilot context, RAM use, and build behavior all get worse.
|
|
|
|
## What To Do Now
|
|
|
|
While the architecture is still being decided:
|
|
|
|
- Keep the solution small and intentional.
|
|
- Use the repo-root project only as a workspace placeholder or solution anchor.
|
|
- Keep real implementation in real language/project folders.
|
|
- Do not add vendored, mirrored, archived, or generated folders to the root `.vcxproj`.
|
|
|
|
## When To Create Real Projects
|
|
|
|
Create a real project only when the corresponding codebase actually exists.
|
|
|
|
### C++
|
|
|
|
Create or expand a real `.vcxproj` when there is an actual native code layout such as:
|
|
|
|
- `src/`
|
|
- `include/`
|
|
- `app/`
|
|
- `engine/`
|
|
|
|
At that point the `.vcxproj` should include only first-party native source files and headers.
|
|
|
|
### C#
|
|
|
|
Create a `.csproj` when there is real C# application or library code. Let the `.csproj` represent the actual source tree instead of routing C# through the root `.vcxproj`.
|
|
|
|
### Node / TypeScript
|
|
|
|
Create an `.njsproj` only when there is a real frontend, tool, server, or plugin root with files such as:
|
|
|
|
- `package.json`
|
|
- `src/`
|
|
- `public/`
|
|
- `tests/`
|
|
|
|
The Node project should point only at that app folder and should explicitly ignore `node_modules`, build output, caches, and mirrors.
|
|
|
|
### Rust
|
|
|
|
Use `Cargo.toml` as the source of truth. Do not force Rust code into a C++ project. When the crate layout is real, wire Visual Studio around the Rust crate deliberately.
|
|
|
|
### Unreal
|
|
|
|
If `HyperTwist` grows around Unreal, let Unreal-generated project structure remain the source of truth for Unreal modules and plugin code. Do not dump Unreal `Intermediate` or generated build output into the root `.vcxproj`.
|
|
|
|
## When To Ask Codex To Set It Up
|
|
|
|
Come back and ask for setup when one of these is true:
|
|
|
|
- the first real app folder has been created
|
|
- the first real language-specific project exists
|
|
- you want the multi-project solution updated cleanly
|
|
- you want Copilot/Visual Studio indexing to recognize the app roots properly
|
|
|
|
Good examples:
|
|
|
|
- "Create a proper Node.js project for `ui/`."
|
|
- "Turn `engine/src` and `engine/include` into the real C++ project."
|
|
- "Add the Rust crate and keep it out of the root `.vcxproj`."
|
|
- "Wire the Unreal plugin/tooling folders into the solution without indexing generated output."
|
|
|
|
## What Not To Do
|
|
|
|
- Do not use the repo-root `.vcxproj` as a catch-all for the entire repository.
|
|
- Do not include `mirrors`, archives, downloaded reference material, or generated folders.
|
|
- Do not rely on `Show All Files` plus a giant root project as the long-term structure.
|
|
- Do not assume Visual Studio will "organically" infer the right architecture later if the placeholder project is already polluted.
|
|
|
|
## Practical Bootstrap Sequence
|
|
|
|
1. Decide the first real code roots.
|
|
2. Create the real language-native project files for those roots only.
|
|
3. Keep the repo-root project minimal.
|
|
4. Exclude generated, mirrored, vendored, and research-only directories from indexing.
|
|
5. Rebuild the solution index after structural changes.
|
|
|
|
## Short Version
|
|
|
|
Until the real code layout exists, keep `HyperTwist.vcxproj` minimal.
|
|
|
|
Once real C++, C#, Node/TypeScript, Rust, or Unreal code roots exist, ask Codex to wire those folders into proper project files instead of expanding the root workspace project.
|