Added and updated docstrings.

README

@@ -19,4 +19,11 @@ Requirements:
 ####### Packaging #######
 #########################
 
-Can be built into apk for android using buildozer, for windows using pyinstaller.
+Can be built into apk for android using buildozer, for windows (EXE-file) using
+pyinstaller.
+
+buildozer.spec is part of this repository and must be slightly altered to work
+on your system. See comments in buildozer.spec for more detail.
+
+Windows build has been tested using pyinstaller installed into a wine environment.
+main.spec can be altered and used with pyinstaller to build EXE-files.

buildozer.spec

@@ -87,7 +87,11 @@ fullscreen = 1
 #android.ant_path =
 
 # (str) python-for-android git clone directory (if empty, it will be automatically cloned from github)
-#android.p4a_dir = /home/lars/Dev/python-for-android/
+############ ALTER THIS LINE TO BUILD ON YOUR SYSTEM!! ###############
+# CUSTOM python-for-android is used for version-pinning and custom recipes
+# like cplanet. Put the engine_src/cplanet directory of this repository to the recipes
+# folder of your python-for-android so cplanet is available to be installed into
+# the apk.
 android.p4a_dir = /home/lars/Dev/python-for-android/
 #android.p4a_dir = %(source.dir)s/.buildozer/android/platform/python-for-android-master/
 

context_slider.py

@@ -8,7 +8,7 @@
 class Context_Slider(FloatLayout):
 
     '''
-    labeled slider with changing context
+    labeled slider with changing context depending on current game-mode
     '''
 
     logic = ObjectProperty(None)

gamezone.py

@@ -9,6 +9,12 @@
 import time
 from random import randint
 
+'''
+This is the widget where the actuall simluation is displayed.
+Scatter widget can be zoomed, translated and rotated which is basically the
+zooming functionality. Hands down touch events to current mode.
+'''
+
 
 class Gamezone(Scatter):
 

infobox.py

@@ -8,6 +8,12 @@
 from kivy.uix.slider import Slider
 from kivy.app import App
 
+'''
+Infoxbox displayed on the top right when a body is seleceted. Recieves
+Planet dictionary in update method to display planet information in
+corresponding labels
+'''
+
 
 class Infobox(ScrollView):
 

main.py

@@ -18,6 +18,13 @@
 import os.path
 import time
 
+'''
+main module of application. entry point when application is run. build-method
+is run first, on_start and on_stop fire when app is actually started or closed.
+
+also contains load/save mechanism for settings and savegames.
+'''
+
 
 class PlanetApp(App):
 

main.spec

@@ -3,7 +3,6 @@ from kivy.deps import sdl2, glew
 
 block_cipher = None
 
-
 a = Analysis(['main.py'],
              pathex=['C:\\PlanetAppV2'],
              binaries=[],

mainscreen.py

@@ -21,6 +21,11 @@
 from infobox import Infobox
 from seltoggles import Seltoggles
 
+'''
+Screen shown when the game is played. Contains gamezone and control widgets.
+Divides touch events for control widgets and gamezone and hands them down.
+'''
+
 
 class MainScreen(Screen):
     '''
@@ -103,16 +108,20 @@ def on_leave(self):
             self.logic.tutorial_mode = False
 
     def allign_gamezone(self):
+        # center gamezone widget so simulation starts in the middle
         self.gamezone.center_x = self.center_x
         self.gamezone.center_y = self.center_y
 
-    # hand down touch events, hand to gamezone if nothing else matches
     def on_touch_down(self, touch):
+        # hand down touch events, hand to gamezone if nothing else matches
         for widget in self.interface:
+            # dont check invisible widgets
             if widget not in self.children:
                 continue
+            # gamezone is last
             if widget == self.gamezone:
                 continue
+            # check for collision
             if widget.collide_point(touch.x, touch.y):
                 widget.on_touch_down(touch)
                 return
@@ -164,6 +173,7 @@ def build_interface(self):
         )
 
         self.gamezone = Gamezone(
+            # zooming stuff
             # do_rotation=False,
             # do_translation_y=False,
             # do_translation_x=False,
@@ -200,17 +210,19 @@ def build_interface(self):
         )
 
         self.value_slider.bind(value=self.value_slider_change)
-
         self.tutorial_label.register_menupanel(self.menupanel)
         self.add_widget(self.menupanel)
-        # self.add_widget(self.label)
 
     def value_slider_change(self, instance, value):
+        # check current mode and update value in logic module
         if self.logic.cur_guimode == self.logic.mode_map['zoom']:
             self.logic.tick_ratio = value
         else:
             self.logic.slider_value = value
-        self.label.text = self.logic.cur_guimode.slider_label + ':' + str(value)
+        # update label
+        self.label.text = ':'.join(
+            [self.logic.cur_guimode.slider_label, str(value)]
+        )
 
     def add_value_slider(self, mode):
         if self.value_slider not in self.children:

menupanel.py

@@ -19,13 +19,13 @@
 from realbutton import RealToggleButton
 from realbutton import RealMenuToggleButton
 
+'''
+menupanel shown on the left side of the screen in mainscreen
+contains main buttons to control the game
+'''
 
-class MenuPanel(FloatLayout):
 
-    '''
-    menupanel shown on the left side of the screen in mainscreen
-    contains main buttons to control the game
-    '''
+class MenuPanel(FloatLayout):
 
     # toggle buttons
     add_planet_button = ObjectProperty(None)
@@ -56,10 +56,8 @@ class MenuPanel(FloatLayout):
     def __init__(self, iconsize, iconratio, **kwargs):
         super(MenuPanel, self).__init__(**kwargs)
         self.logic = App.get_running_app().logic
-
         self.iconsize = iconsize
         self.iconratio = iconratio
-
         self.build_interface()
 
         # keywords to press buttons from other modules

menuscreen.py

@@ -1,21 +1,23 @@
+# KIVY
 from kivy.uix.screenmanager import Screen
 from kivy.uix.screenmanager import FadeTransition
 from kivy.properties import *
 from kivy.app import App
 from kivy.uix.floatlayout import FloatLayout
 from kivy.uix.gridlayout import GridLayout
 from kivy.uix.button import Button
-
-
 from kivy.core.window import Window
+
+# CUSTOM
 from realbutton import RealButton
 
+'''
+Menuscreen shown when app has started. Access savegames, settings, credits and
+tutorial from here.
+'''
 
-class MenuScreen(Screen):
 
-    '''
-    add fancy main menu here!
-    '''
+class MenuScreen(Screen):
 
     startbutton = ObjectProperty(None)
     tutorialbutton = ObjectProperty(None)

planet.py

@@ -3,12 +3,12 @@
 from kivy.properties import *
 from kivy.uix.floatlayout import FloatLayout
 
+'''
+this widget is used to show planets in the gamezone
+'''
 
-class Planet(FloatLayout):
 
-    '''
-    this widget is used to show planets in mainscreen
-    '''
+class Planet(FloatLayout):
 
     base_image = ObjectProperty(None)
     select_overlay = ObjectProperty(None)

realbutton.py

@@ -5,6 +5,10 @@
 from kivy.uix.behaviors import ToggleButtonBehavior
 from kivy.clock import Clock
 
+'''
+custom button mechanics due to problems with texture scaling in kivy buttons
+'''
+
 
 class RealButton(ButtonBehavior, Image):
 

savegamescreen.py

@@ -12,17 +12,18 @@
 from slot import Slot
 from realbutton import RealButton
 
+'''
+This screen will provide gui to save and load savegames
+from json-files
+savegame-files are:
+save_current.json -> allways keep current game
+save_1.json -> First savegame-slot
+[...]
+save_5.json -> last savegame-slot
+'''
+
 
 class SavegameScreen(Screen):
-    '''
-    This screen will provide gui to save and load savegames
-    from json-files
-    savegame-files are:
-    save_current.json -> allways keep current game
-    save_1.json -> First savegame-slot
-    [...]
-    save_5.json -> last savegame-slot
-    '''
 
     buttonlayout = ObjectProperty(None)
     mainlayout = ObjectProperty(None)

seltoggles.py

@@ -19,6 +19,11 @@
 from realbutton import RealMenuToggleButton
 from realbutton import RealTimedButton
 
+'''
+buttons shown on the right bottom when a planet is selected. needs to be
+updated depending on planet data (fixed) and logic fixview mode
+'''
+
 
 class Seltoggles(FloatLayout):
 
@@ -103,6 +108,8 @@ def build_interface(self):
         self.add_widget(self.planet_fixview_button)
 
     def update(self, **kwargs):
+        # update buttons depending in planet selected. kwargs contain
+        # complete planet dictionary and fixview flag from logic
         fixed = kwargs.get('fixed', False)
         fixview = kwargs.get('fixview', False)
         fixbutton = self.planet_fix_button

settingsscreen.py

@@ -13,6 +13,11 @@
 from realbutton import RealButton
 from slot import SettingsSlot
 
+'''
+screen to alter settings. basically a scrollview containing settings slots.
+also access kivy settings from here.
+'''
+
 
 class SettingsScreen(Screen):
 

slot.py

@@ -11,6 +11,11 @@
 # CUSTOM
 from realbutton import RealToggleButton
 
+'''
+Slot = widget to show savegame-slot
+SettingsSlot = widget to show settings item
+'''
+
 
 class Slot(FloatLayout):
 

tutorial_label.py

@@ -5,13 +5,13 @@
 
 from realbutton import RealButton
 
+'''
+simple tutorial mechanics working with states mapped in two dictionaries
+state_texts and state_actions
+'''
 
-class Tutorial_Label(FloatLayout):
 
-    '''
-    simple tutorial mechanics working with states mapped in two dictionaries
-    state_texts and state_actions
-    '''
+class Tutorial_Label(FloatLayout):
 
     label = ObjectProperty(None)
     menupanel = ObjectProperty(None)