diff --git a/src/types.ts b/src/types.ts
index d393ec3d..7b683f8f 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -103,6 +103,41 @@ export interface KaboomCtx {
 	make<T>(comps?: CompList<T>): GameObj<T>,
 	/**
 	 * Remove and re-add the game obj, without triggering add / destroy events.
+	 * @example
+	 * ```js
+	 * // Common way to use this is to have one sprite overlap another sprite, and use readd() to have the bottom sprite on top of the other.
+	 * 
+	 * // Create two sprites.
+	 * const greenBean = add([
+	 * sprite("bean"),
+	 * pos(200,140),
+	 * color(255, 255, 255),
+         * area(),
+	 * ])
+	 * 
+	 * // This bean will overlap the green bean.
+	 * const purpleBean = add([
+	 * sprite("bean"),
+	 * pos(230,140),
+	 * color(255, 0, 255),
+  	 * area(),
+	 * ])
+	 * 
+	 * // Example 1: simply call readd() on the target you want on top.
+	 * readd(greenBean)   
+	 * 
+	 * // Example 2: using onClick() or other functions with readd().
+	 * // If you comment out the first example, and use this readd() with a function like onClick(), you
+	 * can keep switching which sprite is above the other ( click on edge of face ).
+	 * 
+	 * purpleBean.onClick(() => {
+	 * 		readd(greenBean)
+	 * })
+	 *        
+	 * greenBean.onClick(() => {
+	 * 		readd(purpleBean)
+	 * })
+	 * ```
 	 */
 	readd(obj: GameObj): void,
 	/**