Conversation
docs/how_to_play.md
Outdated
| TODO: Include this documentation in compiled releases and suggest that the user read that documentation to ensure that documentation changes discussing unreleased functionality don't cause confusion. Note that we likely don't need to include most documentation in compiled releases, since the target audience of most documentation will be contributors, not players. | ||
|
|
||
| #### Troubleshooting | ||
| TODO: Fill this out after we have logfiles a user can reference. Make sure to suggest updating graphics drivers with some pointers on how to do this. Potentially just copy from wiki. |
There was a problem hiding this comment.
Not sure this section does any good without content. Are there even any common issues known?
There was a problem hiding this comment.
I'm mainly thinking of Vulkan issues and graphics driver issues in general. However, I think I agree that we can just get rid of this section for now. It can be added later on if we find common issues.
|
|
||
| A common issue is that a dependency is missing, or a tool cannot find it because it is missing in PATH. For example, Git needs to be installed and in the PATH. To check whether Git is configured correctly, open a shell and run `git --version`. | ||
|
|
||
| The "shaderc" dependency also has some complications. Unless you have a preinstalled version of shaderc, compiling Hypermine will try to compile shaderc from scratch, which requires CMake and Python 3 as dependencies (See the help page for shaderc linked above). On Windows, you will also need the "Ninja" build system. |
There was a problem hiding this comment.
Compiling shaderc is never necessary and should be strongly discouraged. Linux users can install it from repositories; windows users can get it from the Vulkan SDK.
There was a problem hiding this comment.
I think fixing this may be out of scope for the PR, as the Windows 10 building instructions in the Wiki have suggested similarly for years (https://github.com/Ralith/hypermine/wiki/Installation-instructions-for-Windows-10).
If we want to discourage people from building shaderc from source, we should probably disable it entirely so that the error message can be more straightforward.
I haven't found building shaderc from source to be particularly problematic (just requiring a few extra dependencies), so since this is in the troubleshooting section, I don't think we need to make any changes here for now.
There was a problem hiding this comment.
I reread https://github.com/google/shaderc-rs?tab=readme-ov-file#setup, and it looks like there isn't a way to disable building from source entirely. This would have been nice, as the error message would have been a lot more helpful, but that likely means that I should spend a bit more effort in the documentation guiding the user towards installing the Vulkan SDK or installing shaderc directly, instead of installing things like Python and ninja.
patowen
force-pushed
the
how-to-play-docs
branch
from
c7c1a4e to
44e03e3
Compare
2 participants
I believe that clear official documentation on how to play Hypermine would be useful to make it easier to support new potential players. I went ahead and drafted an initial version.