pipmak-users

[Pipmak-Users] Basic Mac help

[Liam S. <Li...@fr...>]

As it seems Pipmak is aimed at people who are not serious game  
coders, is there any chance that someone could create some kind of  
documentation, even if it was just a page long, to tell people how to  
do basic stuff, like open the Pipmak Demo and see/use the code, for  
people who do not have a background in programming.

 From looking at the Pipmak numbered files, and reading the  
discussion of how the program works, it seems like there would be a  
relatively short learning curve in order to start breaking into  
Pipmak. Of course, real expertise and artful use would take longer  
and require more learning.

But as it is, for someone without a basic understanding of how to get  
started, one can't do anything. And none of the Lua sites (that I can  
find anyway) give a basic overview of any of this. All of them are  
aimed at people who are already programmers and are new to Lua only.

What is needed is a basic step by step process that introduces first  
the new paradigm of writing programs on a mac and goes from there.  
ie. Does one have to install Lua for Mac on your machine first? If so  
how is that done? How does one see/work on/ "compile" (hard as it may  
seem to understand, to many many people, compiling is not a concept  
many people have any idea of) files? What is the "Console" program  
and how does it work - again there is no reference material on any of  
this anywhere I can find.

As it is, all the documentation assumes a level of programming  
understanding beyond what I would assume many of the possible users  
of Pipmak have.

I only share this as I have talked to many people who might use  
Pipmak and become loyal users/developers/community members, if only  
they could find a little help with understanding what is basically a  
new paradigm. In general, most such people come from other  
disciplines, graphic experts/3d modellers, interactive fiction  
writers, etc.

If the goal is not for Pipmak to become a kind of middleware for a  
larger user base then I would understand not wanting to offer this  
help - though it would seem that is self-defeating, as those who  
already understand programming are inherently a group less in need of  
the program.

Good luck.

Liam

Liam Shannon
Creative Director
Fresh Cut Grass Advertising

22 Everett Street
Sherborn, MA 01770
(508)545-2125

[Pipmak-Users] Re: Basic Mac help

[Urs H. <ur...@an...>]

Hi

> As it seems Pipmak is aimed at people who are not serious game
> coders, is there any chance that someone could create some kind of
> documentation, even if it was just a page long, to tell people how to
> do basic stuff, like open the Pipmak Demo and see/use the code, for
> people who do not have a background in programming.

Would it be useful to have a step by step tutorial that describes how to
create a simple pipmak-project? Do you mean something like this?

>  From looking at the Pipmak numbered files, and reading the
> discussion of how the program works, it seems like there would be a
> relatively short learning curve in order to start breaking into
> Pipmak. [...]

Right. Games that don't need some special features are easily created.

> But as it is, for someone without a basic understanding of how to get
> started, one can't do anything. And none of the Lua sites (that I can
> find anyway) give a basic overview of any of this. All of them are
> aimed at people who are already programmers and are new to Lua only.

http://www.lua.org/
I see your problem. For the first steps in pipmak, you do not need to
know anything about lua at all. You only have to create images and
hotspot-maps. Like this you can already create a few panoramas, for
example a little island on which you can walk around. To create the
corresponding .lua-files, you only have to copy and modify some
statements. You can take the ones from the demo project of pipmak.
(Look at the end of this post.)

> What is needed is a basic step by step process that introduces first
> the new paradigm of writing programs on a mac and goes from there.
> ie. Does one have to install Lua for Mac on your machine first? If so
> how is that done? How does one see/work on/ "compile" (hard as it may
> seem to understand, to many many people, compiling is not a concept
> many people have any idea of) files? What is the "Console" program
> and how does it work - again there is no reference material on any of
> this anywhere I can find.

In order to create a pipmak-game (or project if you want), you do not
need to compile pipmak itself. Lua is linked statically into pipmak, so
you don't even have to install lua. Just download the newest build of
pipmak for the mac.

> As it is, all the documentation assumes a level of programming
> understanding beyond what I would assume many of the possible users
> of Pipmak have.

The main problem seems to be to find the information you need. 

> I only share this as I have talked to many people who might use
> Pipmak and become loyal users/developers/community members, if only
> they could find a little help with understanding what is basically a
> new paradigm. In general, most such people come from other
> disciplines, graphic experts/3d modellers, interactive fiction
> writers, etc.

Graphic experts and 3d modellers? Advice them immediately to use pipmak!
I hope to see a free, graphically fantastic game on pipmak! (Dreams ...
some become true.)

> If the goal is not for Pipmak to become a kind of middleware for a
> larger user base then I would understand not wanting to offer this
> help - though it would seem that is self-defeating, as those who
> already understand programming are inherently a group less in need of
> the program.

As I'm not the author of pipmak, I'm not saying anything about the
destination of pipmak. But for me it's like this: I have some
programming skills, but wouldn't be able to write my own "Myst"-engine
from scratch. Exactly such an engine is Pipmak. With Pipmak, I can
concentrate on the game and am not bothered with technical thigs like
OpenGL and protability. Unfortunately, I do not have much time at the
moment to develop my game. So progress is only made very slowly.

A simple pipmak-project:

main.lua looks like this:

  version (0.23)

  title "Pipmak simple project"
  startnode (1)

OK, node 1 is our first position in a virtual world.
Save all Images you need for this position in the folder 1.
In 1/node.lua write the following:

  cubic { "01.jpeg", "02.jpeg", "03.jpeg", "04.jpeg", "05.jpeg",
"06.jpeg" }

  hotspotmap "hotspots.png"

  hotspot { target = 2 }
  hotspot { target = 35 }

Do the same thing for every position (node). If you have done this, you
can already wolk around in your virtual world. How the images 01.jpg to
06.jpg and hotspots.png should look like should be described in the
documentation to pipmak. You dont have to compile anything, simply load
main.lua with pipmak!

Greetings
Urs

[Pipmak-Users] Re: Basic Mac help

[Christian W. <cwa...@gm...>]

Hi Liam

Urs has already said a lot of what I'd have answered, but let me (as 
Pipmak's author) elaborate on some points.

First of all, thanks for bringing up the topic. I sometimes worry that 
there might be a lot of people in a similar situation to yours, 
potential Pipmak users, but who are too busy or afraid or whatever to 
ask questions (that I would happily answer) and so are turned away from 
Pipmak.

Let me explain why the state of documentation for Pipmak is what it is. 
The reason I did not start with writing a tutorial (or other entry-level 
documentation) is that I'm not too fond of tutorials myself. I usually 
find that I learn faster by examining examples, doing my own 
experiments, and looking things up in reference documentation. That's 
why I provide examples (the demo project that contains examples of how 
to use any of Pipmak's features) and reference documentation 
(Reference.pdf, which is still incomplete, but should be quite usable by 
now). I realize that this style of documentation, essentially tailored 
to myself, may not be the right thing, or not sufficient, for other 
people. Therefore I would be very happy to have some complementary 
entry-level documentation, such as a simple tutorial, for Pipmak. I have 
not written such documentation myself for the following reasons:

1. There is still a lot to do in Pipmak code-wise. Doing this requires 
programming skills, and having in-depth knowledge of Pipmak's code makes 
it easier. Since I am the one who currently has more of that knowledge 
than anyone else, that looks like a job for me (but contributions are 
still welcome, of course). Entry-level documentation, on the other hand, 
can just as well (or maybe even better) be written by a contributor 
without programming skills (but perhaps better writing and teaching 
skills than mine). So, it seems to me that time is better spent with me 
programming and a contributor writing documentation than me writing 
documentation and the contributor doing nothing.

2. If I were to write entry-level documentation, it would inevitably end 
up in the same style as the reference (and the comments in the demo 
project). That means that if you don't understand some concept in the 
reference, you possibly also wouldn't understand it in a tutorial 
written by me. In addition, I may neglect to properly explain things 
that (subconsciously) seem obvious to me as a programmer and as someone 
perfectly familiar with Pipmak. An outsider, on the other hand, seeing 
things with fresh eyes, may be able to explain them in different ways 
and anticipate beginners' problems better.

In short, I heartily encourage anyone who would like to help improve 
Pipmak to consider writing such documentation. Maybe you? Don't forget 
that I'm here to answer your questions, you don't have to be an expert. 
I'm willing to guide you as much as necessary, this still is less work 
for me than writing a full tutorial.


> But as it is, for someone without a basic understanding of how to get 
> started, one can't do anything. And none of the Lua sites (that I can 
> find anyway) give a basic overview of any of this. All of them are aimed 
> at people who are already programmers and are new to Lua only.

As Urs already said, you don't need to know anything about Lua for 
simple projects. So I guess the problem for me to solve is how to better 
make people aware of that.

> What is needed is a basic step by step process that introduces first the 
> new paradigm of writing programs on a mac and goes from there. ie. Does 
> one have to install Lua for Mac on your machine first? If so how is that 
> done? How does one see/work on/ "compile" (hard as it may seem to 
> understand, to many many people, compiling is not a concept many people 
> have any idea of) files? What is the "Console" program and how does it 
> work - again there is no reference material on any of this anywhere I 
> can find.

It's not necessary to install anything, it's not necessary to compile 
anything, and it's not necessary to use the console. Is there anything 
in Pipmak's documentation or on the web site that is giving you the 
impression you'd have to do any of these things? The question is meant 
to sound friendly, not arrogant - I'm genuinely interested, because if 
there is, that's something I need to fix.

> As it is, all the documentation assumes a level of programming 
> understanding beyond what I would assume many of the possible users of 
> Pipmak have.

That may be true, but it's not meant to. I'd like to change that, but I 
need help. Do you think an additional piece of entry-level documentation 
would alleviate the problem, or are there also things that need to be 
explained more throroughly in the reference?

It's true that authoring a Pipmak project currently means writing text 
files, and not dragging stuff around with your mouse, but don't let that 
discourage you. It need not have much to do with programming if you 
don't want to. In addition, graphical editing features are planned (some 
fragments are even in place already, but as they aren't really useful 
yet, they're hidden by default).

> I only share this as I have talked to many people who might use Pipmak 
> and become loyal users/developers/community members, if only they could 
> find a little help with understanding what is basically a new paradigm. 
> In general, most such people come from other disciplines, graphic 
> experts/3d modellers, interactive fiction writers, etc.

It would be very exciting to have those people. Although I'm hesitant to 
encourage too much evangelism at this point because Pipmak is really not 
suited yet for more ambitious projects (the most important missing 
features are sound and movies), people who are willing to actively 
participate and help each other out are very welcome.

I think the main problem at this time is that Pipmak is still 
essentially a one-man project, which means that it progresses very 
slowly, both on the feature front and the support/documentation front.

Thanks for your thoughts!

  -Christian

[Pipmak-Users] Re: Basic Mac help

[Urs H. <ur...@an...>]

Hi all

Christian Walther wrote:
> [...]

> [...] So, it seems to
> me that time is better spent with me programming and a contributor
> writing documentation than me writing documentation and the
> contributor doing nothing.

Haha! Do you allow me to quote that?

> [...]

> It would be very exciting to have those people. Although I'm hesitant
> to encourage too much evangelism at this point because Pipmak is
> really not suited yet for more ambitious projects (the most important
> missing features are sound and movies), people who are willing to
> actively participate and help each other out are very welcome.

True.
I wonder how fast those people could come up with graphically pleasing
data for a Pipmak project.

> I think the main problem at this time is that Pipmak is still
> essentially a one-man project, which means that it progresses very
> slowly, both on the feature front and the support/documentation front.

True. Remember: slow progress is better than no progress. Up to now, I
learned one thing: Honour the little achievements! 

cu

[Pipmak-Users] Re: Basic Mac help

[Christian W. <cwa...@gm...>]

Urs Holzer wrote:
>> [...] So, it seems to
>> me that time is better spent with me programming and a contributor
>> writing documentation than me writing documentation and the
>> contributor doing nothing.
> 
> Haha! Do you allow me to quote that?

If you take it out of context like this, rather not. :) The comment 
applies to entry-level "getting started" documentation, not to 
documentation in general. I want to make clear that I'm *not* avoiding 
documenting the code I write. I try hard to write reference 
documentation for every new feature I implement at the same time (i.e. 
before the feature first appears in a release).

The "outsider perspective" thing is important too, and it clearly 
doesn't apply to reference documentation.

  -Christian