2 files changed, 73 insertions, 61 deletions

diff --git a/README.md b/README.md
index 3e8a4a6b..852d0ac3 100644
--- a/README.md
+++ b/README.md
@@ -1,76 +1,88 @@
-# Intro
+# re3
+[![Build status](https://ci.appveyor.com/api/projects/status/hyiwgegks122h8jg?svg=true)](https://ci.appveyor.com/project/aap/re3/branch/master)
+<a href="https://discord.gg/jYpXxTm"><img src="https://img.shields.io/badge/discord-join-7289DA.svg?logo=discord&longCache=true&style=flat" /></a>
+<a href="https://ci.appveyor.com/api/projects/aap/re3/artifacts/bin/Debug/re3.dll?branch=master&job=Configuration%3A+Debug"><img src="https://img.shields.io/badge/download-debug-9cf.svg" /></a>
+<a href="https://ci.appveyor.com/api/projects/aap/re3/artifacts/bin/Release/re3.dll?branch=master&job=Configuration%3A+Release"><img src="https://img.shields.io/badge/download-release-blue.svg" /></a>
+
+## Intro
 
 The aim of this project is to reverse GTA III for PC by replacing
 parts of the game [one by one](https://en.wikipedia.org/wiki/Ship_of_Theseus)
 such that we have a working game at all times.
 
-Apparently you can download a binary of the latest version here:
-[Debug](https://ci.appveyor.com/api/projects/aap/re3/artifacts/bin/Debug/re3.dll?branch=master&job=Configuration%3A+Debug), 
-[Release](https://ci.appveyor.com/api/projects/aap/re3/artifacts/bin/Release/re3.dll?branch=master&job=Configuration%3A+Release).
+## How can I try it?
 
-Build status:
-[![Build status](https://ci.appveyor.com/api/projects/status/hyiwgegks122h8jg?svg=true)](https://ci.appveyor.com/project/aap/re3/branch/master)
+- re3 requires game assets to work, so you need to own a copy of GTA III.
+- Since re3 is a DLL that works with original GTA III for now, you need Simple DLL Loader. You can get it [here](https://github.com/aap/simpledllloader).
+- Build re3 or download it from one of the above links (Debug or Release).
+- Make sure you included the re3 in `plugins.cfg` or `dlls.cfg`.
+- re3 starts the script `main_freeroam.scm` that comes along with it by default, so you should copy it to from `gamefiles/` to your game's `data/` directory.
+
+![#ffa500](https://placehold.it/15/ffa500/000000?text=+) **Notice**
+
+If you want to load original script/story, press and hold G while game is loading.
+This includes both starting new game and loading save game.
+
+![#ffa500](https://placehold.it/15/ffa500/000000?text=+) **Notice if you will build it**
+
+There are various settings at the very bottom of `config.h`, you may want to take a look there. i.e. FIX_BUGS define fixes the bugs we've come across.
 
-Re3 starts the script main_freeroam.scm by default. Make sure you copy it to your data directory.
+https://github.com/GTAmodding/re3/blob/readme/src/core/config.h
 
-# Strategy
+## I want to contribute, where should I start?
 
 A good approach is to start at the fringes of the code base,
 i.e. classes that don't depend on code that we don't have reversed yet.
 If a function uses only few unreversed functions that would be inconvenient
 to reverse at the time, calling the original functions is acceptable.
 
-# Progress
-
-This is a list of some things that have been reversed to some non-trivial extent.
-Not everything is listed, check the code.
-(TODO: keep this list at least a bit up to date...)
-
+### Unreversed / incomplete classes (at least the ones we know)
 ```
-CPool
-CTxdStore
-CVector
-CVector2D
-CMatrix
-CModelInfo
-CBaseModelInfo
-CSimpleModelInfo
-CTimeModelInfo
-CClumpModelInfo
-CPedModelInfo
-CVehicleModelInfo
-CVisibilityPlugins
-CRenderer
-CSprite
-CSprite2d
-CFont
-CEntity
-CPhysical
-CCollision
-CCullZones
-CTheZones
-CPathFind
+CAudioManager, cDMAudio, cSampleManager and all audio - being worked on
+CAccidentManager
+CBoat
+CBrightLights
+CBulletInfo
+CBulletTraces
 CCam
-CParticle
-CParticleMgr
-CPointLights
-CCoronas
-CAntennas
-CClouds
-CHud
+CCamera
+CCivilianPed
+CCopPed
+CCrane
+CCranes
+CCullZone
+CCullZones
+CEmergencyPed
+CExplosion
+CFallingGlassPane
+CFire
+CFireManager
+CGame
+CGarage
+CGarages
+CGlass
+CMenuManager
+CMotionBlurStreaks
+CPacManPickups
+CPed - being worked on
+CPedIK
+CPhoneInfo - one function left
+CPlayerInfo
+CPlayerPed
+CProjectile
+CProjectileInfo
+CRoadBlocks
+CRunningScript - being worked on
+CStats
+CSpecialFX
+CTrafficLights
+CWaterCannon
+CWaterCannons
+CWeapon
+CWeaponEffects
 ```
 
-# Low hanging fruit
-
-There are a couple of things that have been reversed for other projects
-already that could probably be put into this project without too much effort.
-Again, the list is not complete:
-
-* ~~Animation (https://github.com/aap/iii_anim)~~
-* File Loader (https://github.com/aap/librwgta/tree/master/tools/IIItest)
-* ...
-
-# Coding style
+### Coding style
 
 I started writing in [Plan 9 style](http://man.cat-v.org/plan_9/6/style),
 but realize that this is not the most popular style, so I'm willing to compromise.
@@ -178,7 +190,7 @@ but here are some observations:
 
 * Generally, try to make the code look as if R* could have written it
 
-# Environment Variables
+### Environment Variables
 Here you can find a list of variables that you might need to set in windows:
 ```
 "GTA_III_RE_DIR" * path to "gta3_re" game folder usually where this plugin run.
diff --git a/src/core/config.h b/src/core/config.h
index 4ceb701d..175a5f61 100644
--- a/src/core/config.h
+++ b/src/core/config.h
@@ -144,17 +144,17 @@ enum Config {
 #	define CHATTYSPLASH	// print what the game is loading
 #endif
 
-#define FIX_BUGS		// fix bugs in the game, TODO: use this more
+#define FIX_BUGS		// fixes bugs that we've came across during reversing, TODO: use this more
 
 // Pad
 #define KANGAROO_CHEAT
 
 // Hud & radar
 #define ASPECT_RATIO_SCALE
-#define TRIANGULAR_BLIPS
+#define TRIANGULAR_BLIPS	// height indicating triangular radar blips, as in VC
 
 // Script
-#define USE_DEBUG_SCRIPT_LOADER
+#define USE_DEBUG_SCRIPT_LOADER	// makes game load main_freeroam.scm by default
 
 // Vehicles
 #define EXPLODING_AIRTRAIN	// can blow up jumbo jet with rocket launcher
@@ -165,6 +165,6 @@ enum Config {
 
 // Peds
 #define ANIMATE_PED_COL_MODEL
-#define VC_PED_PORTS
-#define NEW_WALK_AROUND_ALGORITHM
+#define VC_PED_PORTS			// various ports from VC's CPed, mostly subtle
+#define NEW_WALK_AROUND_ALGORITHM	// to make walking around vehicles/objects less awkward
 #define CANCELLABLE_CAR_ENTER