diff --git a/examples/HMCPI.hs b/examples/HMCPI.hs --- a/examples/HMCPI.hs +++ b/examples/HMCPI.hs @@ -34,6 +34,8 @@ import Control.Monad (when) import Control.Proxy +import Data.Version (showVersion) + import Network (PortID (..), connectTo) import System.Environment (getArgs, getProgName) @@ -43,6 +45,8 @@ , hPutStrLn, hSetBuffering , stderr, stdin, stdout ) +import Paths_mcpi (version) + -- | Link together the two handles, so that content -- moves from the first to the second. -- @@ -106,5 +110,7 @@ main :: IO () main = do args <- getArgs - if null args then mcpi else usage + if null args + then putStrLn ("HMCPI - version " ++ showVersion version) >> mcpi + else usage diff --git a/examples/README b/examples/README deleted file mode 100644 --- a/examples/README +++ /dev/null @@ -1,56 +0,0 @@ - -There are several programs, illustrating some very *basic* -interactions with MineCraft-PI. - -*) freefall - -Source code: Freefall.hs - -Usage: - freefall - freefall jump - -Increase the height of the player by jump blocks. If not specified the -jump is 100 blocks. A check is made to ensure that the jump does not -place the player into a block. Messages are sent to MineCraft to -inform the player what is happening. - -There is no check that jump is valid (e.g. is positive, or not so -great that it exceeds the limits of the world), but this could be -added quite easily. - -*) flatten - -Source code: Flatten.hs - -Usage: - flatten - flatten radius - -Flatten the area surrounding the user, converting the floor into gold -and removing any blocks above it. The area converted is a circle of -the given radius (this defaults to 5 if not given). The central tile -is not counted, so that a radius of 1 will change the blocks in front -of, behind, and to the side of the player. - -There is no check that the blocks that are added are actually -supported, although this could be added by an enterprising programmer. - -*) hmcpi - -Source code: HMCPI.hs - -Usage: - hmcpi - hmcpi < filename - -This provides a direct interface to MineCraft-PI. You enter the full -commands, such as chat.post(Hello World!) or world.getBlock(0,0,0), -and see the response from the game. The program is essentially telnet -but specialized to only talk to MineCraft. There is currently no -attempt at providing a nicer interface, such as help, automatic -completion of commands, or cleaning user input. - -Note that this program does not take use the hmcpi library, since it -is a low-level interface. - diff --git a/examples/README.md b/examples/README.md new file mode 100644 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,65 @@ + +There are several programs, illustrating some very *basic* +interactions with MineCraft-PI. + +*) freefall + +Source code: Freefall.hs + +Usage: + freefall + freefall jump + +Increase the height of the player by jump blocks. If not specified the +jump is 100 blocks. A check is made to ensure that the jump does not +place the player into a block. Messages are sent to MineCraft to +inform the player what is happening. + +There is no check that jump is valid (e.g. is positive, or not so +great that it exceeds the limits of the world), but this could be +added quite easily. + +*) flatten + +Source code: Flatten.hs + +Usage: + flatten + flatten radius + +Flatten the area surrounding the user, converting the floor into gold +and removing any blocks above it. The area converted is a circle of +the given radius (this defaults to 5 if not given). The central tile +is not counted, so that a radius of 1 will change the blocks in front +of, behind, and to the side of the player. + +There is no check that the blocks that are added are actually +supported, although this could be added by an enterprising programmer. + +*) hmcpi + +Source code: HMCPI.hs + +Usage: + hmcpi + hmcpi < filename + +This provides a direct interface to MineCraft-PI. You enter the full +commands, such as chat.post(Hello World!) or world.getBlock(0,0,0), +and see the response from the game. The program is essentially telnet +but specialized to only talk to MineCraft. There is currently no +attempt at providing a nicer interface, such as help, automatic +completion of commands, or cleaning user input. + +Note that this program does not take use the hmcpi library, since it +is a low-level interface. + +*) xjump + +Source code: XJump.hs + +Usage: + xjump + +Move the player by 10 tiles in the X direction if the tile is not +filled. diff --git a/examples/XJump.hs b/examples/XJump.hs new file mode 100644 --- /dev/null +++ b/examples/XJump.hs @@ -0,0 +1,26 @@ +{-# LANGUAGE RecordWildCards #-} + +module Main where + +import Control.Monad (when) + +import Data.MineCraft.Pi.Block +import Data.MineCraft.Pi.Player +import Data.MineCraft.Pi.Other +import Data.MineCraft.Pi.Types + +import Network.MineCraft.Pi.Client + +-- | Move the player by 10 tiles in the X direction, +-- if it is not filled. +movePlayer :: MCPI () +movePlayer = do + Pos {..} <- getPlayerTile + let newPos = Pos (_x+10) _y _z + bType <- getBlock newPos + when (bType == air) $ do + setPlayerTile newPos + chatPost "*jump*" + +main :: IO () +main = runMCPI movePlayer diff --git a/mcpi.cabal b/mcpi.cabal --- a/mcpi.cabal +++ b/mcpi.cabal @@ -1,5 +1,7 @@ -name: mcpi -Version: 0.0.0.1 +Name: mcpi +Version: 0.0.0.2 +Homepage: https://github.com/DougBurke/hmcpi +Bug-Reports: https://github.com/DougBurke/hmcpi/issues Stability: experimental License: PublicDomain Author: Douglas Burke (dburke.gw@gmail.com) @@ -8,28 +10,30 @@ Synopsis: Connect to MineCraft running on a Raspberry PI. Description: The MineCraft edition for Raspberry PI comes with a Java and - Python API. + Python API. See "Network.MineCraft.Pi.Client" for a basic + example. . This is a *very* basic, and *incomplete* Haskell version. I fully expect everything to change in later versions. . - Two very simple examples are included in the examples/ directory, - as well as a way to interact with MineCraft directly. + A number of very simple examples are included in the examples/ directory, + as well as a program that lets you interact with MineCraft directly. . - Please see the TODO file in the source code for an incomplete - list of possible changes. + Please see the TODO.md file in the source code for an incomplete + list of possible changes, and the CHANGES.md file for changes + in the module. Tested-With: GHC==7.4.1 Cabal-Version: >= 1.8 Build-Type: Simple --- #Source-repository head --- # type: mercurial --- # location: https://bitbucket.org/doug_burke/grabtweets - -Data-Files: examples/README +Data-Files: examples/README.md examples/*.hs +source-repository head + type: git + location: git://github.com/DougBurke/hmcpi.git + Flag build-examples Description: Build the example programs (defaults to True) Default: True @@ -37,7 +41,7 @@ Library Build-Depends: base >=3 && < 5, - network == 2.3.*, + network >= 2.3 && < 2.5, split == 0.2.*, transformers == 0.3.* @@ -91,6 +95,7 @@ Main-Is: HMCPI.hs Hs-Source-Dirs: examples/ + Other-Modules: Paths_mcpi ghc-options: -Wall @@ -98,7 +103,7 @@ Build-Depends: base, network, - pipes == 3.1.* + pipes >= 3.0 && < 3.2 Executable isongold if !flag(build-examples) @@ -112,5 +117,18 @@ Build-Depends: base, - mcpi, - transformers + mcpi + +Executable xjump + if !flag(build-examples) + Buildable: False + + Main-Is: XJump.hs + Hs-Source-Dirs: examples/ + + ghc-options: + -Wall + + Build-Depends: + base, + mcpi diff --git a/src/Data/MineCraft/Pi/Block.hs b/src/Data/MineCraft/Pi/Block.hs --- a/src/Data/MineCraft/Pi/Block.hs +++ b/src/Data/MineCraft/Pi/Block.hs @@ -10,7 +10,8 @@ -- Block handling. -- -- It probably makes sense for the block types in --- @Data.MineCraftg.Pi.Types@ - namely @BlockType@ and @BlockData@ +-- "Data.MineCraft.Pi.Types" - namely `Data.MineCraft.Pi.Types.BlockType` +-- and `Data.MineCraft.Pi.Types.BlockData` -- to be moved into this module. -- -- See and @@ -32,8 +33,11 @@ , setBlocks , setBlocksData - -- * Blocks + -- * Utilities + , showBlock + + -- * Block types , air , stone , grass @@ -115,7 +119,7 @@ import Network.MineCraft.Pi.Client import Network.MineCraft.Pi.Client.Internal --- | Block types. +-- | A type of a block. air, stone, grass, dirt, cobblestone, woodPlanks, sapling, bedrock, water, waterStationary, lava, lavaStationary, sand, diff --git a/src/Data/MineCraft/Pi/Camera.hs b/src/Data/MineCraft/Pi/Camera.hs --- a/src/Data/MineCraft/Pi/Camera.hs +++ b/src/Data/MineCraft/Pi/Camera.hs @@ -9,7 +9,7 @@ -- -- Handle the camera position. -- --- *Note* At present this module does not handle multiple users. +-- /Note:/ At present this module does not handle multiple users. -- -------------------------------------------------------------------------------- diff --git a/src/Data/MineCraft/Pi/Other.hs b/src/Data/MineCraft/Pi/Other.hs --- a/src/Data/MineCraft/Pi/Other.hs +++ b/src/Data/MineCraft/Pi/Other.hs @@ -29,12 +29,7 @@ import Network.MineCraft.Pi.Client import Network.MineCraft.Pi.Client.Internal --- | Send a message to the server. --- --- Until I find out otherwise, I am going to assume that --- any conversion done by @show msg@ - such as protecting --- any double quotes - is sufficient. The spec does not --- mention what is required. +-- | Send a message to MineCraft for it to display. -- -- There is no attempt to remove or replace invalid characters. The -- MineCraft server API uses ASCII and it is likely that new lines @@ -44,8 +39,8 @@ chatPost msg = command "chat.post" [msg] -- | Return the height of the world at this position. The spec says --- that the input uses the (x,z) coordinates, but I am assuming this --- is a typo and am using (x,y) instead. +-- that the input uses the @(x,z)@ coordinates, but I am assuming this +-- is a typo and am using @(x,y)@ instead. -- -- It would be easy to test. getHeight :: IPos -> MCPI Int diff --git a/src/Data/MineCraft/Pi/Player.hs b/src/Data/MineCraft/Pi/Player.hs --- a/src/Data/MineCraft/Pi/Player.hs +++ b/src/Data/MineCraft/Pi/Player.hs @@ -9,7 +9,7 @@ -- -- Players in MineCraft. -- --- *Note* this module currently does not support multiple players. +-- /Note:/ This module currently does not support multiple players. -- -------------------------------------------------------------------------------- @@ -31,7 +31,7 @@ import Network.MineCraft.Pi.Client import Network.MineCraft.Pi.Client.Internal --- | Where is the user. See also `getPlayerPos`. +-- | Where is the user? See also `getPlayerPos`. getPlayerTile :: MCPI IPos getPlayerTile = fromMC `liftM` query "player.getTile" [] @@ -39,11 +39,11 @@ setPlayerTile :: IPos -> MCPI () setPlayerTile pos = command "player.setTile" [toMC pos] --- | Where is the user. See also `getPlayerPos`. +-- | Where is the user? See also `getPlayerTile`. getPlayerPos :: MCPI FPos getPlayerPos = fromMC `liftM` query "player.getPos" [] --- | Move the user. See also `setPlayerPos`. +-- | Move the user. See also `setPlayerTile`. setPlayerPos :: FPos -> MCPI () setPlayerPos pos = command "player.setPos" [toMC pos] diff --git a/src/Network/MineCraft/Pi/Client.hs b/src/Network/MineCraft/Pi/Client.hs --- a/src/Network/MineCraft/Pi/Client.hs +++ b/src/Network/MineCraft/Pi/Client.hs @@ -8,18 +8,48 @@ -- Portability : Haskell 98 -- -- The main interface for connecting to the Raspberry-PI version --- of MineCraft. The 'Network.MineCraft.Pi.Client.Internal' module +-- of MineCraft. The "Network.MineCraft.Pi.Client.Internal" module -- provides lower-level access in case this module in insufficient. -- --- There are two types of calls to MineCraft: "command" and "query". +-- There are two types of calls to MineCraft: \"command\" and \"query\". -- Commands change the state of the server and do not return anything, -- queries return information from the server, and presumably does not --- change the server state. This terminology may change. +-- change the server state. This terminology may change. At present +-- there is no check that the call succeeded. -- --- I am not sure the use of the @FromMineCraft@ and @ToMineCraft@ --- type classes is justified, given that the API has a very limited --- set of types. +-- Example: -- +-- In this example we move the player 10 tiles in the X direction, +-- as long as the tile is empty (there is /no/ check that there +-- is anything to stand on). +-- +-- > {-# LANGUAGE RecordWildCards #-} +-- > +-- > module Main where +-- > +-- > import Control.Monad (when) +-- > +-- > import Data.MineCraft.Pi.Block +-- > import Data.MineCraft.Pi.Player +-- > import Data.MineCraft.Pi.Other +-- > import Data.MineCraft.Pi.Types +-- > +-- > import Network.MineCraft.Pi.Client +-- > +-- > -- | Move the player by 10 tiles in the X direction, +-- > -- if it is not filled. +-- > movePlayer :: MCPI () +-- > movePlayer = do +-- > Pos {..} <- getPlayerTile +-- > let newPos = Pos (_x+10) _y _z +-- > bType <- getBlock newPos +-- > when (bType == air) $ do +-- > setPlayerTile newPos +-- > chatPost "*jump*" +-- > +-- > main :: IO () +-- > main = runMCPI movePlayer +-- -------------------------------------------------------------------------------- module Network.MineCraft.Pi.Client @@ -27,6 +57,11 @@ , runMCPI -- * Conversion routines + -- + -- | I am not sure the use of the `FromMineCraft` and `ToMineCraft` + -- type classes is justified, given that the API has a very limited + -- set of types. + -- , FromMineCraft(..) , ToMineCraft(..) @@ -45,7 +80,7 @@ class FromMineCraft a where fromMC :: String -> a --- | Send a value to MineCraft. +-- | Convert a value into a form that can be sent to MineCraft. class ToMineCraft a where toMC :: a -> String diff --git a/src/Network/MineCraft/Pi/Client/Internal.hs b/src/Network/MineCraft/Pi/Client/Internal.hs --- a/src/Network/MineCraft/Pi/Client/Internal.hs +++ b/src/Network/MineCraft/Pi/Client/Internal.hs @@ -10,7 +10,7 @@ -- Portability : RecordWildCards -- -- Internal types for connecting to the Raspberry-PI version --- of MineCraft. Most users are expected to use 'Network.MineCraft.Pi.Client' +-- of MineCraft. Most users are expected to use "Network.MineCraft.Pi.Client" -- rather than this module, but it is provided in case the former -- is not sufficient. --