diff --git a/examples/gg/many_thousands_of_circles_overriding_max_vertices.v b/examples/gg/many_thousands_of_circles_overriding_max_vertices.v
new file mode 100644
index 00000000000000..0a0185f6c1b0d8
--- /dev/null
+++ b/examples/gg/many_thousands_of_circles_overriding_max_vertices.v
@@ -0,0 +1,33 @@
+import gg
+import rand
+
+// The flags here override the default limits for Sokol
+#flag -D_SGL_DEFAULT_MAX_VERTICES=4194304
+#flag -D_SGL_DEFAULT_MAX_COMMANDS=65536
+
+// Without the flags, `max_circles` > 5040, will just show
+// a blue screen without *any circles* drawn.
+const max_circles = 10_000
+
+fn main() {
+	gg.start(
+		window_title: 'Hello'
+		bg_color:     gg.Color{50, 50, 150, 255}
+		width:        800
+		height:       600
+		frame_fn:     fn (ctx &gg.Context) {
+			wsize := gg.window_size()
+			ctx.begin()
+			for _ in 0 .. max_circles {
+				rx := rand.int_in_range(0, wsize.width) or { 0 }
+				ry := rand.int_in_range(0, wsize.height) or { 0 }
+				cr := rand.u8()
+				cg := rand.u8()
+				cb := rand.u8()
+				ctx.draw_circle_filled(rx, ry, 10, gg.Color{cr, cg, cb, 255})
+			}
+			ctx.show_fps()
+			ctx.end()
+		}
+	)
+}
diff --git a/vlib/gg/README.md b/vlib/gg/README.md
index 6fa1bfa7cf3b17..03156bec7f23f2 100644
--- a/vlib/gg/README.md
+++ b/vlib/gg/README.md
@@ -32,4 +32,31 @@ fn frame(mut ctx gg.Context) {
 	ctx.draw_triangle_filled(450, 142, 530, 280, 370, 280, gx.red)
 	ctx.end()
 }
-```
\ No newline at end of file
+```
+
+## Troubleshooting
+
+A common problem, if you draw a lot of primitive elements in the same
+frame, is that there is a chance that your program can exceed the maximum
+allowed amount of vertices and commands, imposed by `sokol`.
+The symptom is that your frame will be suddenly black, after it becomes more complex.
+Sokol's default for vertices is 131072.
+Sokol's default for commands is 32768.
+
+To solve that, you can try adding these lines at the top of your program:
+`#flag -D_SGL_DEFAULT_MAX_VERTICES=4194304`
+`#flag -D_SGL_DEFAULT_MAX_COMMANDS=65536`
+You can see an example of that in:
+https://github.com/vlang/v/blob/master/examples/gg/many_thousands_of_circles_overriding_max_vertices.v
+
+Another approach is to use several draw passes, and limit the amount
+of draw calls that you make in each, demonstrated in:
+https://github.com/vlang/v/blob/master/examples/gg/many_thousands_of_circles.v
+
+Another approach to that problem, is to draw everything yourself in a streaming
+texture, then upload that streaming texture as a single draw command to the GPU.
+You can see an example of that done in:
+https://github.com/vlang/v/blob/master/examples/gg/random.v
+
+A third approach, is to only upload your changing inputs to the GPU, and do all
+the calculations and drawing there in shaders.
diff --git a/vlib/sokol/README.md b/vlib/sokol/README.md
index 29abcff3acafdd..28dd55f7d045ed 100644
--- a/vlib/sokol/README.md
+++ b/vlib/sokol/README.md
@@ -53,3 +53,29 @@ fn main() {
 	audio.shutdown()
 }
 ```
+
+## Troubleshooting sokol apps
+
+A common problem, if you draw a lot of primitive elements in the same frame,
+is that there is a chance that your program can exceed the maximum
+allowed amount of vertices and commands, imposed by `sokol`.
+
+The symptom is that your frame will be suddenly black, after it
+becomes more complex.
+
+Sokol's default for vertices is 131072.
+Sokol's default for commands is 32768.
+
+To solve that, you can try adding these lines at the top of your program:
+`#flag -D_SGL_DEFAULT_MAX_VERTICES=4194304`
+`#flag -D_SGL_DEFAULT_MAX_COMMANDS=65536`
+You can see an example of that in:
+https://github.com/vlang/v/blob/master/examples/gg/examples/gg/many_thousands_of_circles_overriding_max_vertices.v
+
+Another approach to that problem, is to draw everything yourself in a streaming
+texture, then upload that streaming texture as a single draw command to the GPU.
+You can see an example of that done in:
+https://github.com/vlang/v/blob/master/examples/gg/random.v
+
+A third approach, is to only upload your changing inputs to the GPU, and do all
+the calculations and drawing there in shaders.