Skip to content

Commit ce6258e

Browse files
icefoxenicefoxen
authored
Merge pull request ggez#793 from BrettWitty/improve-faq
Improve FAQ
2 parents 6544d0a + 6f892db commit ce6258e

File tree

1 file changed

+141
-61
lines changed

1 file changed

+141
-61
lines changed

‎docs/FAQ.md

+141-61
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,35 @@
1-
# I get `ResourceNotFound("/myfile", ...)` even though it's in the resource dir!
1+
# Table of Contents
2+
3+
* **[Errors](#errors)**
4+
* [I get `ResourceNotFound("/myfile", ...)` even though it's in the resource dir!](#errors_resource)
5+
* [Why do I get `WindowError("Could not create GL context")` when I try to run my game?](#errors_window)
6+
* **[Graphics and GUIs](#gfx)**
7+
* [Can I do 3D stuff?](#gfx_3d)
8+
* [How do I make a GUI?](#gfx_gui)
9+
* [Resolution independence](#gfx_resolution)
10+
* **[Libraries](#libraries)**
11+
* [Can I use `specs`, `legion` or another entity-component system?](#library_ecs)
12+
* **[Performance](#performance)**
13+
* [Image/sound loading and font rendering is slow!](#perf_slow1)
14+
* [Text rendering is still slow!](#perf_text)
15+
* [That's lame, can't I just compile my game in debug mode but ggez with optimizations on?](#perf_debug)
16+
* [Drawing a few hundred images or shapes is slow!](#perf_drawing)
17+
* **[Platform-specific](#platforms)**
18+
* [How do I build on platform X?](#platform_build)
19+
* [Is Mac/iOS supported?](#platform_mac)
20+
* **[Contributing to ggez](#contributing)**
21+
* [If I write X, will you include it in ggez?](#contribute_inclusion)
22+
* **[Miscellaneous](#misc)**
23+
* [How do I load my `conf.toml` file?](#misc_conf)
24+
* [I get a console window when I launch my executable on Windows](#misc_win_console)
25+
26+
---
27+
28+
# Errors
29+
30+
<a name="errors_resource">
31+
32+
## I get `ResourceNotFound("/myfile", ...)` even though it's in the resource dir!
233

334
Okay, first, look at [the docs](https://docs.rs/ggez/) for the
435
`filesystem` module. That should say exactly where it should look for
@@ -19,7 +50,9 @@ If you want to add a non-standard location to the resources lookup
1950
path, you can use `Filesystem::mount()` or
2051
`ContextBuilder::add_resource_path()`; see the examples for examples.
2152

22-
# Why do I get `WindowError("Could not create GL context")` when I try to run my game?
53+
<a name="errors_window">
54+
55+
## Why do I get `WindowError("Could not create GL context")` when I try to run my game?
2356

2457
Basically this means "the graphics driver couldn't give ggez the
2558
graphics settings it's asking for". This usually means "the graphics
@@ -44,7 +77,58 @@ written in the appropriate version of GLSL (which is a bit of a WIP)
4477
and there's no promises that things like `SpriteBatch` and `Canvas`
4578
will work.
4679

47-
# Image/sound loading and font rendering is slow!
80+
<a name="gfx">
81+
82+
# Graphics and GUIs
83+
84+
<a name="gfx_3d">
85+
86+
## Can I do 3D stuff?
87+
88+
Yes; ggez uses `gfx-rs` for its drawing, and you can access the underlying `gfx-rs` drawing functions to draw whatever you want without disrupting ggez's drawing state. See the `cube` example.
89+
90+
In general, ggez is designed to focus on 2D graphics. We want it to be possible for you to create a 3D engine using ggez for everything EXCEPT drawing, but we don't really want to make a full 3D drawing engine. If you want 3D drawing and don't feel like doing it yourself, check out [Amethyst](https://crates.io/crates/amethyst).
91+
92+
<a name="gfx_gui">
93+
94+
## How do I make a GUI?
95+
96+
As of 2017 we know of no good ui options thus far besides "implement
97+
it yourself" or "write a backend for Conrod or something so it can
98+
draw using ggez".
99+
100+
Contributions are welcome! ;-)
101+
102+
<a name="gfx_resolution">
103+
104+
## Resolution independence
105+
106+
By default ggez uses a pixel coordinate system but you can change that
107+
by calling something like
108+
109+
```rust
110+
graphics::set_screen_coordinates(&mut context, Rect::new(0.0, 0.0, 1.0, 1.0)).unwrap();
111+
```
112+
113+
and scaling your `Image`s with `graphics::DrawParam`.
114+
115+
<a name="libraries">
116+
117+
# Libraries
118+
119+
<a name="library_ecs">
120+
121+
## Can I use `specs`, `legion` or another entity-component system?
122+
123+
Sure! ggez doesn't include such a thing itself, since it's more or less out of scope for this, but it is specifically
124+
designed to make it easy to Lego together with other tools. The [game template](https://github.com/ggez/game-template) repo
125+
demonstrates how to use ggez with `specs` for ECS, `warmy` for resource loading, and other nice crates. This template is available with `legion` in place of `specs` as well [here](https://github.com/Quetzal2/game-template).
126+
127+
# Performance
128+
129+
<a name="perf_slow1">
130+
131+
## Image/sound loading and font rendering is slow!
48132

49133
Are you running in debug or release mode? Rust in general is very
50134
slow in debug mode. This causes problems because there is currently no
@@ -70,30 +154,43 @@ opt-level = 2: 430 fps
70154
opt-level = 3: 450 fps
71155
```
72156

73-
# Text rendering is still slow!
157+
<a name="perf_text">
158+
159+
## Text rendering is still slow!
74160

75161
Rendering text to a bitmap is actually pretty computationally expensive. If you call `Text::new()` every single frame it's going to take a relatively large amount of time, and larger bitmaps and more text will take longer.
76162

77163
Ideally you'd be able to use a glyph cache to render letters to a texture once, and then just create a mesh that uses the bits of that texture to draw text. There's a couple partial implementations, such as the [gfx_glyph crate](https://crates.io/crates/gfx_glyph).
78164

79-
# That's lame, can't I just compile my game in debug mode but ggez with optimizations on?
165+
<a name="perf_debug">
166+
167+
## That's lame, can't I just compile my game in debug mode but ggez with optimizations on?
80168

81169
Actually, as of rustc 1.41, you can! See
82170
<https://doc.rust-lang.org/cargo/reference/profiles.html#overrides> for info
83171
on how to do that.
84172

85-
# Drawing a few hundred images or shapes is slow!
173+
<a name="perf_drawing">
174+
175+
## Drawing a few hundred images or shapes is slow!
86176

87177
Again, debug mode is slow. Plus, each single draw call has some overhead. If building in release mode still isn't fast enough, then look into using `SpriteBatch` to draw a bunch of chunks from a spritesheet (also known as an atlas). If you're drawing geometry, instead of using `graphics::rectangle()` or `graphics::circle()` and such, which create a new `Mesh` on each call and then throw it away, create and store a `Mesh` and draw it many times, or use a `MeshBuilder` to build a single `Mesh` out of many separate shapes.
88178

89-
# How do I build on platform X?
179+
<a name="platforms">
180+
181+
# Platform-specific
182+
183+
<a name="platform_build">
184+
185+
## How do I build on platform X?
90186

91187
See the [build
92188
docs](https://github.com/ggez/ggez/blob/master/docs/BuildingForEveryPlatform.md).
93189
If your question is not answered there, open an
94190
[issue](https://github.com/ggez/ggez/issues).
95191

96-
# Is Mac/iOS supported?
192+
<a name="platform_mac">
193+
## Is Mac/iOS supported?
97194

98195
Apple will be supported when they treat programmers trying to use
99196
their systems as something other than third-class citizens. See
@@ -107,61 +204,13 @@ requests for Mac-specific bugs will be accepted as long as they don't
107204
break anything else. In the mean time, consider writing your software
108205
for a company that doesn't treat you like dirt.
109206

110-
# Can I do 3D stuff?
111-
112-
Yes; ggez uses `gfx-rs` for its drawing, and you can access the underlying `gfx-rs` drawing functions to draw whatever you want without disrupting ggez's drawing state. See the `cube` example.
113-
114-
In general, ggez is designed to focus on 2D graphics. We want it to be possible for you to create a 3D engine using ggez for everything EXCEPT drawing, but we don't really want to make a full 3D drawing engine. If you want 3D drawing and don't feel like doing it yourself, check out [Amethyst](https://crates.io/crates/amethyst).
115-
116-
# How do I make a GUI?
117-
118-
As of 2017 we know of no good ui options thus far besides "implement
119-
it yourself" or "write a backend for Conrod or something so it can
120-
draw using ggez".
121-
122-
Contributions are welcome! ;-)
123-
124-
# How do I load my `conf.toml` file?
125-
126-
When you create a `Context` it will automatically look for a
127-
`conf.toml` file in any of the resource directories and, if it finds
128-
one, use that to override all the defaults you give it.
129-
130-
The `files` example should demonstrate this, and more.
131-
132-
# I get a console window when I launch my executable on Windows
133-
134-
You can disable the console entirely by adding the following at
135-
the top of your `main.rs` file:
136-
137-
```rust
138-
#![windows_subsystem = "windows"]
139-
```
140-
141-
If you wish, you can also disable it only in release mode:
142-
143-
```rust
144-
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
145-
```
146-
147-
# Resolution independence
148-
149-
By default ggez uses a pixel coordinate system but you can change that
150-
by calling something like
151-
152-
```rust
153-
graphics::set_screen_coordinates(&mut context, Rect::new(0.0, 0.0, 1.0, 1.0)).unwrap();
154-
```
155-
156-
and scaling your `Image`s with `graphics::DrawParam`.
157-
158-
# Can I use `specs`, `legion` or another entity-component system?
207+
<a name="contributing">
159208

160-
Sure! ggez doesn't include such a thing itself, since it's more or less out of scope for this, but it is specifically
161-
designed to make it easy to Lego together with other tools. The [game template](https://github.com/ggez/game-template) repo
162-
demonstrates how to use ggez with `specs` for ECS, `warmy` for resource loading, and other nice crates. This template is available with `legion` in place of `specs` as well [here](https://github.com/Quetzal2/game-template).
209+
# Contributing
163210

164-
# If I write X, will you include it in ggez?
211+
<a name="contribute_inclusion">
212+
213+
## If I write X, will you include it in ggez?
165214

166215
Maybe, if it's something that fits in with ggez's goals: a simple and flexible 2D game framework with a LÖVE-ish API,
167216
which provides all the basics you need in one package without dictating too much about the more complicated tools.
@@ -187,3 +236,34 @@ ggez on crates.io and get things that are officially supported by the maintainer
187236
example, search for `gfx` on `crates.io` and see how messy the results are.
188237

189238
For a fuller discussion of this, see [issue #373](https://github.com/ggez/ggez/issues/373).
239+
240+
<a name="misc">
241+
242+
# Miscellaneous
243+
244+
<a name="misc_conf">
245+
246+
## How do I load my `conf.toml` file?
247+
248+
When you create a `Context` it will automatically look for a
249+
`conf.toml` file in any of the resource directories and, if it finds
250+
one, use that to override all the defaults you give it.
251+
252+
The `files` example should demonstrate this, and more.
253+
254+
<a name="misc_win_console">
255+
256+
## I get a console window when I launch my executable on Windows
257+
258+
You can disable the console entirely by adding the following at
259+
the top of your `main.rs` file:
260+
261+
```rust
262+
#![windows_subsystem = "windows"]
263+
```
264+
265+
If you wish, you can also disable it only in release mode:
266+
267+
```rust
268+
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
269+
```

0 commit comments

Comments
 (0)