cleaning up in anticipation of new, less confusing layout and docs; removing out-of-date or misleading docs (look in docs/docs-legacy)

Author: Patrick Meehan

README.md

@@ -1,184 +1,67 @@
-# Welcome to Moai!
+Moai SDK is an embeddable cross-platform game development SDK written in C++ and scriptable in Lua. You can use Moai to write games or apps, or you can embed Moai in other programs. You can also use Moai as an overlay in your apps.
 
-Thanks for checking out the Moai source code. Here's the scoop.
+Multiple build systems are supported in this project. Sourcecode is kept in a common folder. There is a separate folder for each build system in the project root.
 
-Linux CI: [![Build Status](https://travis-ci.org/moaiforge/moai-sdk.png?branch=master)](https://travis-ci.org/moaiforge/moai-sdk)
-OSX CI: [![Build Status](https://travis-ci.org/moaiforge/moai-sdk.png?branch=travis-osx)](https://travis-ci.org/moaiforge/moai-sdk)
-## Introduction
+For IDE build systems (Xcode, Android Studio, Visual Studio), reference projects are provided. Cmake is also supported for Android and HTML5.
 
-Moai SDK is an open source game framework for quickly developing great mobile games.
+Third party libraries are included as git submodules (in some cases). The rest are vendored in. As a rule, we do not make any code changes to third party libraries. If functionality must be configured or replaced, we use a header injection pattern to do so.
 
-You can work in Lua or C++, and Moai SDK runs on multiple platforms including iOS, Android, Chrome, Windows, Mac and Linux.
+A goal of the project is one-step build for the reference binaries. We don't want users to have to download and configure dependencies, or build parts of the SDK in advance. If you open the xcode/osx project (for example) and click 'build,' then Moai SDK should build for you in its entirety. This goal isn't always realized across all platforms, but it is something we strive for and if you want contribute build process improvements, please keep this goal in mind.
 
-## Download
-Please clone the source in the following way.
+The project's principal developer (patrickmeehan) primarily works on OSX these days. As a result, the xcode/osx project is typically the most actively maintained. (For major releases, we update and test all projects.)
 
-    git clone https://github.com/moai/moai-dev.git
-    cd moai-dev
-    git submodule init
-    git submodule update
+### pito
 
-## Setup
-Tools needed to build the MOAI SDK.
+pito is a command line toolbelt for automating some aspects of the project. pito is just a bootstrapper that use command line Moai to run lua scripts. To use pito, make sure moai-dev/pito is somewhere in your path. When you first run pito, if the Moai binary is missing, pito will attempt to build it.
 
-* [Android SDK](http://developer.android.com/sdk/index.html)
-* [Android NDK](http://developer.android.com/tools/sdk/ndk/index.html) (32bit Only, r8e or earlier)
-   * windows: http://dl.google.com/android/ndk/android-ndk-r8e-windows-x86.zip
-   * linux: http://dl.google.com/android/ndk/android-ndk-r8e-linux-x86_64.tar.bz2
-   * osx: http://dl.google.com/android/ndk/android-ndk-r8e-darwin-x86_64.tar.bz2	 
-* [Java SE 6](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
-* [Ant 1.9](http://ant.apache.org/)
-* [CMake 2.8.11](http://www.cmake.org/)
-* [Ruby 1.9](http://www.ruby-lang.org/)
-* [Visual Studio 2010](http://www.visualstudio.com/) (Windows only)
-* [XCode 4 or 5](https://itunes.apple.com/app/xcode/id497799835?mt=12) (Mac only)
-* [MinGW64 TCC](http://tdm-gcc.tdragon.net/) (Windows only, needed for android luajit support or can build mingw version of moai)
-* [Emscripten](https://github.com/kripken/emscripten)
- 
-The following tools are required to build the API documentation.
+At the Moai SDK project level, pito does very little beyond generating the HTML documentation for Moai's Lua interface and running some build scripts that can be used for CI. If you want to extend pito with other commands, type 'pito help' on the command line and you will see an explanation of how pito searches upward through the directory hierarchy for extensions.
 
-* [Bundler](http://gembundler.com/)
-* [Doxygen](http://www.doxygen.org/)
+### Project Structure
 
-On Mac OSX some tools need to be installed with homebrew:
+* __3rdparty__ - Submodules and third party source.
+* __3rdparty/contrib__ - Third party code snippets included in Moai.
+* __android-ndk__ - Android JNI build project.
+* __android-studio__ - Android Studio reference project.
+* __bin__ - Moai executables, organized by OS type, generated by the various build systems.
+* __cmake__ - Cmake build project.
+* __docs__ - Legal notices and attribution images. Run 'pito make-lua-docs' to generate API reference.
+* __lib__ - Moai static libraries, organized by OS type, generated by the various build systems.
+* __pito__ - Moai command line utility.
+* __samples__ - Moai SDK desktop and mobile samples.
+* __samples-legacy__ - Old samples from the before-time. We'll bring these forward Soon(tm).
+* __src__ - All Moai SDK source code for Moai libraries and hosts.
+* __test__ - This is a legacy, Lua-based test runner. Will be replaced by Google Test.
+* __vs2015__ - Visual Studio reference build system and reference project.
+* __xcode__ - Xcode build system and reference projects.
 
-    $ brew install xctool ios-sim cmake
-    
-    cmake needs to be 3.3 on osx
+Be sure to check for README files in these folders.
 
-On Mac OSX, Linux and Windows, Android studio version should be 1.4+ and 
-Android ndk can be r10e+
+### Reference Projects
 
+Reference projects are the projects we use for day-to-day development work on Moai. We do not provide any kind of Moai project generator or IDE templates (though this functionality is somewhat provided by Cmake). The usage pattern for Moai is to copy one of the reference projects, manually update the paths to either the Moai source or libraries, and tailor it to your needs. This might sound onerous, but in our experience, if you know how to use the IDEs it should only take you a few minutes.
 
-Please set the following environment variables.
+In the past, members of the community have provided extensions to pito that generate high quality IDE projects from project templates. We don't maintain these in moai-dev; the moai-community repository was created to hold them.
 
-### Mac OSX
+### Hey, there aren't any docs! How do I use this thing?
 
-	export MOAI_BIN=<install_path>/moai-dev/release/osx/host-sdl/bin
-	export MOAI_CONFIG=<install_path>/moai-dev/samples/config
+Start with command line Moai. Add moai-dev/bin/<os> to your path then run some of the samples. We try to keep these up to date, but don't always have time (though for official releases of the SDK they all should work).
 
-### Linux
+The samples are very, very simple. You will find Moai to be unopinionated and low-level. It is very much intended to be an SDK. You can piece it together however you want to make your game or app.
 
-	export MOAI_BIN=<install_path>/moai-dev/release/linux/host-sdl/x64/bin
-	export MOAI_CONFIG=<install_path>/moai-dev/samples/config
+Once you get the hang of using Moai, start your project using a window size that uses a resolution/aspect ration you are comfortable with. You can adapt this later to handle multiple resolutions and aspect ratios. It is fine to prototype on desktop; mobile support is robust enough that you can port your work once you have something going.
 
-### Windows
+### How do I get help?
 
-	set MOAI_BIN=<install_path>\moai-dev\release\win32\host-sdl\bin
-	set MOAI_CONFIG=<install_path>\moai-dev\samples\config
+There's no official support for the project right now. Check the forums or see if you can get an invite to the Slack team.
 
-## Build Hosts
-Please build according to the following procedure.
+If you have lots of money and want to hire someone to work on features for you or help you with your Moai project, you can try your luck by emailing 'moai-sdk' at fallguyconsulting.com.
 
-### Windows Host
+### Tips
 
-	cd moai-dev
-	.\bin\build-win.bat
-	
-### OSX Host
-
-	# Build
-	cd moai-dev
-	./bin/build-osx.sh
-	
-	# Run
-	cd <sample_directory>
-	$MOAI_BIN/moai main.lua
-
-### iOS Host
-
-	cd moai-dev
-	./bin/build-ios.sh <lua_dir>
-
-### Linux Host
-
-	# Build
-	cd moai-dev
-	./bin/build-linux-sdl.sh
-	
-	# Run
-	$MOAI_BIN/moai main.lua
-
-### Android Host
-
-	# Build
-	export ANDROID_NDK=<path_to_android_ndk>
-	cd moai-dev
-	./bin/build-android.sh
-	
-	# Edit Setting
-	cd release/android/host
-	vi settings-global.sh
-	vi settings-local.sh
-	
-	# Run
-	./run-host.sh
-
-### HTML Host
-    
-    #build
-    export EMSCRIPTEN_HOME=<path_to_emscripten_1.7.1>
-    cd moai-dev
-    ./bin/build-html.sh
-
-    #run
-    <http-serve> cmake/build/host-template/www
-
-    #see src\host-html\readme.md for more info
-
-## Create IDE Projects
- 
-### Visual Studio
-Execute `create-projects-win.bat` in `moai-dev\bin`.
-By default, this creates a Visual Studio 2012 solution in `moai-dev\cmake\projects\vs2012`. To generate project files for a different version of Visual Studio, specify your desired version (`vs2008`, `vs2010`, `vs2012`, or `vs2013`) as a command-line argument.
-
-### iOS
-    ./bin/create-projects-ios.sh
-    open cmake/projects/moai-ios/moai.xcproj
-
-### OSX
-    ./bin/create-projects-osx.sh
-	open cmake/projects/moai-osx/moai.xcproj
-
-## Sample code
-Go to the samples folder, which contains dozens of samples that can be run using one the hosts located in ant (Android), xcode (OSX and iOS), or Visual Studio (Windows).
-
-One of our priorities is to build richer samples for Moai developers, so if you'd like to see a particular code sample, let us know by posting in the [Moai forums](http://getmoai.com/forums/).
-
-## License
-
-This SDK uses the [CPAL license](http://www.opensource.org/licenses/cpal_1.0). Refer to the  for attribution screens to include with games made with Moai.
-
-## Forks
-
-* [patrickmeehan/moai-dev](https://github.com/patrickmeehan/moai-dev)
-* [moaiforge/moai-sdk](https://github.com/moaiforge/moai-sdk)
-
-## Links
-
-### Moai Pages
-
-* [Moai Web Site](http://www.getmoai.com/)
-* [Moai FAQ](http://getmoai.com/marketing/moai-faqs.html)
-* [Moai SDK Framework Reference](http://getmoai.com/docs/)
-* [Moai forums](http://getmoai.com/forums/)
-* [Moai Wiki(getmoai)](http://getmoai.com/wiki/)
-* [Moai Wiki(github)](https://github.com/moai/moai-dev/wiki)
-* [Moai API Documentation](http://moaiforge.github.io/moai-sdk/api/latest/).
-* [MoaiFiddle](http://moaifiddle.com/) An online Moai editor and player.
-* [Moai Site Redesign Proposal](http://moaiwebsite.github.io/)
-
-### Tutorials
-* [GameFromScratch MOAI Tutorials](http://www.gamefromscratch.com/page/Moai-tutorial-series-The-adventures-of-an-intrepid-programmer-in-the-lands-of-Moai.aspx)
-* [moaisnippets](http://www.moaisnippets.info/)
-
-### Libraries
-* [Rapanui](https://github.com/ymobe/rapanui)
-* [Hanappe](https://github.com/makotok/Hanappe)
-* [MOAI GUI](https://github.com/derickd/moaigui)
-* [Shilke2D](https://github.com/Shrike78/Shilke2D)
-* [Spine MOAI](https://github.com/tangerinagames/spine-moai)
-
-### Tools
-* [moaicli](http://halfnelson.github.io/moaicli/)
-* [MoaiUtils](https://github.com/DanielSWolf/MoaiUtils/blob/master/README.md)
+* For any kind of serious app, you will need to figure out how to handle transitions yourself (screen-to-screen or level-to-level). There is no official way of doing this.
+* Don't get too wrapped up in writing class systems of abstractions on top of Lua or Moai. At least not at first. A light touch is usually the way to go.
+* Moai does not attempt to hide or abstract low-level graphics concepts. To get the most out of Moai, you will need to understand coordinate systems and shaders. Game development is hard. Our goal is to provide convenience, flexibility and power, not to simplify.
+* You will eventually need to manage the garbage collector and hunt down objects that get left in scope. Don't worry: when you get there you will find that there are powerful mechanism in Lua and some memory analysis tools build in to Moai that will make this tractable.
+* Once you understand Moai viewports and scale settings, you will understand how you can write your app to use a device-independent coordinate system. For 2D games, you will be able to update your assets to use higher or lower resolutions without changing object dimensions. In our projects, we typically use at our highest targeted resolution for all assets and downsample for lower resolution devices.
+* Plan your letterboxing scheme early. You will want to decide up front if you will reposition UI elements or draw extra UI to avoid black bars.
+* Prototype on desktop, but test (a bunch) on device, well ahead of release.

docs/.gitignore

@@ -0,0 +1 @@
+lua-docs-html/