api style document 1

from the recent dialog on the dev list i see its time to put this together. while Arc is the maintainer the rewrite thats underway (the third by my count) should learn from our history lest we repeat past mistakes.

• always group dimensions/channels/aspects in one attribute
  
  
  • something.position=(x,y,z) not something.x something.y something.z
  
  
  • something.color=(r,g,b) not something.red something.green something.blue
  
  
  • something.volume=(l,r) not something.leftvolume something.rightvolume
  
  
  • something.size=(w,h) not something.width something.height


• combine aspects of one thing in one class
  
  
  • entity.mesh entity.shape entity.mass
  
  
  • scene == audio field + visible scene + ode world + ode space


• inherit often + group in same submodule
  
  
  • every widget should inherit same base class in soy.widgets
  
  
  • every entity should inherit base entity class in soy.entities
  
  
  • every camera should inherit base camera class in soy.cameras


• init should be implicit
  
  
  • opengl, openal, ode should all init when first used


• there should never be only one possible of any thing
  
  
  • multiple windows
  
  
  • multiple background music
  
  
  • multiple controllers
  
  
  • multiple game servers


• idiotproof without treating users as idiots
  
  
  • allow users to do stupid things that dont crash pysoy
  
  
  • agressive type checking to ensure pysoy wont crash
  
  
  • out of bounds arguments should silently change to nearest inbound value
  
  
  • let user create large scenes that drop fpu very low, good for learning
  
  
  • when possible let same thing be used for multiple other things:
    
    
    • allow video as texture on widget and mesh
    
    
    • allow sound to attach to widget or entity
    
    
    • abstract api on these things to make this simple


• when in doubt consider the following (in order)
  
  
  1. which solution is most intuitive
  
  
  2. which solution would produce the smallest api
  
  
  3. which solution requires the least user-side code to use
  
  
  4. which solution offers most flexibility
  
  
  5. which solution leads to higher fps